Codebase Outline

Directory Structure:

• .github/ GitHub configuration files
• .vscode/ Visual Studio Code configuration files & extension packaging scripts
• media/ Transpiled TypeScript and CSS output of the web folder
• node_modules/ Required node modules installed by running npm install
• out/ Transpiled TypeScript output of src folder
• resources/ Media resources (e.g. icon and readme animations)
• src/ Extension back end TypeScript files
• web/ Webview front end TypeScript and CSS files

Extension Back-end

• askpass/*
  • Integration with askpass (used by Git to prompt the user for credentials for remotes).
  • It creates an IPC channel and sets environment variables so that askpass credential requests from Git commands (run in child processes) are received by the extension, which can then prompt the user to provide the credentials.
• avatarManager.ts
  • Manages fetching avatars from the various avatar providers.
  • Saves avatars in a local cache.
  • Sends a Data URI of the avatar to the frontend for display.
• config.ts
  • Abstracts the Visual Studio Code workspace settings, providing default values for unset configuration variables.
• dataSource.ts
  • Executes Git commands and parses output into the corresponding output objects
• diffDocProvider.ts
  • Provides documents at specific commits, in order to view the commit file diff.
• gitGraphView.ts
  • Manages the creation of the webview
  • Responsible for communication with the front end
• extension.ts
  • Registers the git-graph.view command, and triggers webview creation
  • Registers the text document content document provider for commit diff viewing
  • Manages status bar icon
• extensionState.ts
  • Exposes get and set methods interfacing with the global and workspace Visual Studio Code extension Memento's
• repoFileWatcher.ts
  • Watches the current repository for file changes, triggering the view to refresh when needed.
  • Debounces file system events so that if multiple files change at once, only a single refresh is triggered.
  • Provides a mute/unmute mechanism so that git commands don't trigger an unnecessary view refresh.
• repoManager.ts
  • Watches the current workspace folders to detect when repositories are added or removed, triggering the view to refresh when needed.
  • Searches workspace subdirectories for repositories.
• statusBarItem.ts
  • Handles the creation of the Git Graph status bar item
  • Shows/hides the status bar item depending on the configuration setting and whether the active workspace contains any git repositories.

Webview Front-end

• dropdown.ts
  • Custom dropdown element respecting the Visual Studio Code colour scheme
  • Used by the repo and branch dropdowns in the top control bar
• findWidget.ts
  • Implementation of the Find Widget used to search commits, and highlight & navigate between matches.
• graph.ts
  • Graph generation and rendering
  • Contains classes: Vertex, Branch & Graph
• main.ts
  • Renders the front-end (e.g. controls, commits, context menus, dialogs, ...)
  • Responsible for communication with the back-end
  • Manages event listeners
• utils.ts
  • Constants and helper methods used throughout the front-end

Message Passing

The front and back end components of the application communicate using the standard Node.js Child Process message passing pattern, in the files src/gitGraphView.ts (back end) and web/main.ts (front end).

Messages sent from the front end to the back end are all of type RequestMessage.

RequestMessage = {
    command: '<command_name>',
    command specific request arguments
}

Messages sent from the back end to the front end are all of type ResponseMessage. There are two types of response messages, depending on the type of error produced by the specific command:

• All Git commands use the error variant, as they can provide a useful error message to the user.

ResponseMessage = {
    command: '<command_name>',
    <command specific data fields>,
    error: string | null (null => no error occurred, otherwise => error message)
}

• Commands that don't provide a useful error output & are likely to never throw an error (e.g. copying data to the clipboard) use the success variant, and just return a boolean to indicate success or failure.

ResponseMessage = {
    command: '<command_name>',
    success: boolean (true => command successful, false => command failed)
}