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.
• 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
• gitGraphView.ts
  • Manages the creation and disposal of the Webview
  • Responsible for communication with the front end, and making passing requests onto the appropriate backend function.
• logger.ts
  • Provides logging via a Visual Studio Code Output Channel with a set of easy to use methods.
• 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.
• utils.ts
  • Provides a variety of general purpose utility functions to support the other classes.
  • Provides some extension specific wrappers to some Visual Studio Code API integrations.

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, that is 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
• settingsWidget.ts
  • Implementation of the Settings Widget, that is used to view and update the repositories Git configuration.
• utils.ts
  • Constants and helper methods used throughout the front-end

Message Passing

The front and back end components of the extension 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)
}

Types

Git Graph uses TypeScript across all code to ensure type safety, increase the speed of development, and provide transpiling to allow the latest JavaScript features to be used while still targeting the supported ES versions in Visual Studio Code. The pattern used by this extension for type definition is as follows.

Types can be defined in three different locations within this extension:

• Class specific types that will only be used within a single file are included in the same file as they are used (either at the top or bottom).
• Types used across multiple classes in the backend code are defined in src/types.ts. All types defined in src/types are made available to the frontend via the GG namespace (after backend compilation). Types defined here are typically data, config, or message related as they are used across the entire extension.
• Types used across multiple classes in the frontend code are defined in web/global.d.ts.