Git

There is integrated support for working with git and git forges in the code editor.

Here's an overview of all currently supported features:

• Committing
• Staging, pushing, pulling, and fetching
• Project Diff: A multibuffer view of all changes
• Diff indicators in buffers and editor scrollbars
• Inline diff toggle and reverts in the editor for unstaged changes
• Git status in the Project Panel
• Branch creating and switching
• Git blame viewing
• Git stash pop, apply, drop and view

Git Panel

The Git Panel provides a birds-eye view of the state of the working tree and staging area.

Open the Git Panel using git_panel::ToggleFocus, or by clicking the Git icon in the status bar.

The Git Panel shows the state of the project: Which repository and branch are active, what files have changed and the current staging state of each file.

Gram monitors the project repository, so any changes made within or outside the editor are instantly visible in the git panel.

Configuration

Configure how the editor hard wraps commit messages with the preferred-line-length setting of the "Git Commit" language. The default is 72, but it can be set to any number of characters, 0 or more.

The Git Panel also allows configuring the soft_wrap setting to adjust how commit messages display while typing them in the Git Panel. The default setting is editor_width, however, none, preferred_line_length, and bounded are also options.

Example

"languages": {
  "Git Commit": {
    "soft_wrap": "editor_width",
    "preferred_line_length": 72
  },
}

Project Diff

See all of the current changes by opening the Project Diff ({#kb git::Diff}), accessible via the git::Diff action in the Command Palette or the Git Panel.

All of the changes displayed in the Project Diff behave the same as any other multibuffer: they are all editable excerpts of files.

Stage or unstage each hunk as well as a whole file by hitting the buttons on the tab bar or their corresponding keybindings.

Fetch, push, and pull

Fetch, push, or pull from the Git repository in Gram via the buttons available on the Git Panel or via the Command Palette actions: git::Fetch, git::Push, and git::Pull.

Staging Workflow

Gram has two primary staging workflows, using either the Project Diff or the panel directly.

Using the Project Diff

In the Project Diff view it's possible to focus on each hunk and stage them individually by clicking on the tab bar buttons or via the keybindings git::StageAndNext ({#kb git::StageAndNext}).

Similarly, stage all hunks at the same time with the git::StageAll ({#kb git::StageAll}) keybinding and then immediately commit with git::Commit ({#kb git::Commit}).

Using the Git Panel

From the panel, simply type a commit message and hit the commit button, or git::Commit. This will automatically stage all tracked files (indicated by a [·] in the entry's checkbox) and commit them.

Entries can be staged using each individual entry's checkbox. All changes can be staged using the button at the top of the panel, or git::StageAll.

Committing

There are two ways to commit changes from within the editor:

1. Using the button at the bottom of the Git Panel. Hitting {#kb git::Commit} immediately commits all of your staged changes.
2. Invoke the action git::ExpandCommitEditor or use the keyboard shortcut {#kb git::ExpandCommitEditor} while focused on the Git Panel commit text area.

Undo a commit

As soon as you commit in Gram, in the Git Panel, you'll see a bar right under the commit textarea which will show the most recently submitted commit.

In there, you can use the "Uncommit" button, which will run a command similar to git reset HEADˆ --soft.

Commit Line Length

By default, the commit line length is set to 72. It can be configured in settings.json.

See preferred-line-length in the Configuration section.

Stashing

Git stash allows you to temporarily save your uncommitted changes and return to a clean working directory. This is useful to quickly switch branches or pull updates without committing incomplete work.

Creating Stashes

To stash all current changes, use the git::StashAll action. This will save both staged and unstaged changes to a new stash entry and set up a clean working directory.

Managing Stashes

Gram provides a comprehensive stash picker accessible via git::ViewStash. From the stash picker, you can:

• View stash list: Browse all your saved stashes with their descriptions and timestamps
• Open diffs: See exactly what changes are stored in each stash
• Apply stashes: Apply stash changes to your working directory while keeping the stash entry
• Pop stashes: Apply stash changes and remove the stash entry from the list
• Drop stashes: Delete unwanted stash entries without applying them

Quick Stash Operations

For faster workflows, Gram provides direct actions to work with the most recent stash:

• Apply latest stash: Use git::StashApply to apply the most recent stash without removing it
• Pop latest stash: Use git::StashPop to apply and remove the most recent stash

Stash Diff View

When viewing a specific stash in the diff view, you have additional options available through the interface:

• Apply the current stash to your working directory
• Pop the current stash (apply and remove)
• Remove the stash without applying changes

To open the stash diff view, select a stash from the stash picker and use the stash_picker::ShowStashItem ({#kb stash_picker::ShowStashItem}) keybinding.

Git Integrations

Gram integrates with popular Git hosting services to ensure that Git commit hashes and references to Issues, Pull Requests, and Merge Requests become clickable links.

Gram currently supports links to the hosted versions of GitHub, GitLab, Bitbucket, Sourcehut and Codeberg.

For self-hosted GitHub, GitLab, or Bitbucket instances, add them to the git_hosting_providers setting so commit hashes and permalinks resolve to your domain:

{
  "git_hosting_providers": [
    {
      "provider": "gitlab",
      "name": "Corp GitLab",
      "base_url": "https://git.example.corp",
    },
  ],
}

Copy Permalink

Create a permanent link to a code snippet on your Git hosting service.

These links are useful for sharing a specific line or range of lines in a file at a specific commit. Trigger this action via the Command Palette (search for permalink), by creating a custom key bindings to the editor::CopyPermalinkToLine or editor::OpenPermalinkToLine actions or by simply right clicking and selecting Copy Permalink with line(s) selected in your editor.

Diff Hunk Keyboard Shortcuts

When viewing files with changes, Gram displays diff hunks that can be expanded or collapsed for detailed review:

• Expand all diff hunks: editor::ExpandAllDiffHunks ({#kb editor::ExpandAllDiffHunks})
• Collapse all diff hunks: Press Escape (bound to editor::Cancel)
• Toggle selected diff hunks: editor::ToggleSelectedDiffHunks ({#kb editor::ToggleSelectedDiffHunks})
• Navigate between hunks: editor::GoToHunk and editor::GoToPreviousHunk

Tip: The Escape key is the quickest way to collapse all expanded diff hunks and return to an overview of your changes.

Action Reference

| Action | Keybinding | | ----------------------------------------- | ------------------------------------- | | git::Add | {#kb git::Add} | | git::StageAll | {#kb git::StageAll} | | git::UnstageAll | {#kb git::UnstageAll} | | git::ToggleStaged | {#kb git::ToggleStaged} | | git::StageAndNext | {#kb git::StageAndNext} | | git::UnstageAndNext | {#kb git::UnstageAndNext} | | git::Commit | {#kb git::Commit} | | git::ExpandCommitEditor | {#kb git::ExpandCommitEditor} | | git::Push | {#kb git::Push} | | git::ForcePush | {#kb git::ForcePush} | | git::Pull | {#kb git::Pull} | | git::PullRebase | {#kb git::PullRebase} | | git::Fetch | {#kb git::Fetch} | | git::Diff | {#kb git::Diff} | | git::Restore | {#kb git::Restore} | | git::RestoreFile | {#kb git::RestoreFile} | | git::Branch | {#kb git::Branch} | | git::Switch | {#kb git::Switch} | | git::CheckoutBranch | {#kb git::CheckoutBranch} | | git::Blame | {#kb git::Blame} | | git::StashAll | {#kb git::StashAll} | | git::StashPop | {#kb git::StashPop} | | git::StashApply | {#kb git::StashApply} | | git::ViewStash | {#kb git::ViewStash} | | editor::ToggleGitBlameInline | {#kb editor::ToggleGitBlameInline} | | editor::ExpandAllDiffHunks | {#kb editor::ExpandAllDiffHunks} | | editor::ToggleSelectedDiffHunks | {#kb editor::ToggleSelectedDiffHunks} |

Not all actions have default keybindings, but can be bound by customizing your keymap.

Git CLI Configuration

If you would like to also use Gram for your git commit message editor when committing from the command line you can use gram --wait:

git config --global core.editor "gram --wait"

Or add the following to your shell environment (in ~/.zshrc, ~/.bashrc, etc):

export GIT_EDITOR="gram --wait"