GeezerVison

After installing GitComet, open a repository and work through a review, stage, and commit cycle.

Check Git and your identity

GitComet requires Git 2.53 or newer. Open Settings with Cmd+, on macOS or Ctrl+, on Windows and Linux, then select Executables to see the detected version and path. Choose a custom executable if your preferred Git installation is not on the application's PATH.

Git uses your configured name and email for commits. If you have not set them, run these commands inside your repository to configure them for that repository:

git config user.name "Your Name"
git config user.email "[email protected]"

Use git config --global instead if you want the same identity as the default for all your repositories.

Open or clone a repository

• Open an existing repository: press Cmd+O or Ctrl+O and choose its folder. You can also drag a repository folder into GitComet.
• Clone a remote repository: open the command palette with Cmd+P or Ctrl+P, choose Clone Repository, and enter the remote URL and destination. The clone dialog shows progress and lets you cancel.
• Start a new repository: follow Init, then open the folder in GitComet.

If the gitcomet command is available in your terminal, you can open a repository directly:

gitcomet /path/to/repo

On Linux and macOS, the command returns once the GitComet window opens, and the app keeps running after you close the terminal. To keep GitComet attached to the terminal, for example to watch its log output or to make a script wait until the window closes, pass --foreground or set GITCOMET_FOREGROUND=1:

gitcomet --foreground /path/to/repo

git difftool and git mergetool sessions always wait for the tool window to close.

GitComet opens repositories in tabs. Use Cmd+Shift+O or Ctrl+Shift+O to find open and recently closed repositories; the list keeps your 150 most recent repositories.

Workspaces And Windows

A workspace groups the repositories in a window. Open a new window with Cmd+N or Ctrl+N, then open repositories in it. Settings → Workspaces lets you manage saved workspaces, their names, colors and theme overrides.

A workspace is saved once you open a repository in it. Giving it a name, title-bar color or theme keeps it saved even after its last repository closes.

Press Cmd+Shift+R or Ctrl+Shift+R to open a saved workspace. In an empty window it opens there; otherwise GitComet focuses or opens the workspace's own window. Right-click a repository tab and choose Move to new window or Move to a named workspace to reorganize your tabs.

Workspaces group projects in GitComet. A linked worktree is a separate Git checkout; you can open worktrees in workspace tabs just like other repositories.

Find your way around

The command palette also provides actions such as Create Branch, Fetch All, Reload Repository, and Open Settings. Context menus on files, commits, and branches expose actions for the selected item.

Make your first commit

1. Edit a file in your usual editor, or open a working-tree file in GitComet and press Option+E on macOS or Alt+E on Windows and Linux to enter the built-in editor. Save with Cmd+S or Ctrl+S while the editor is open.
2. Select the changed file in the working copy and review its diff.
3. Stage the file, or use the diff gutter to stage only the hunks or lines that belong together. In a working-tree diff, Space stages or unstages the current file and advances to an adjacent file.
4. Review the staged diff. This is the content Git will commit; later unstaged edits remain outside the commit.
5. Enter a commit message and choose Commit, or Commit & Push to publish the commit straight away. With the message input focused, Cmd+Enter or Ctrl+Enter activates Commit and Cmd+Shift+Enter or Ctrl+Shift+Enter activates Commit & Push when they are enabled. If the commit fails, for example because a pre-commit hook rejects it, GitComet keeps your message so you can fix the problem and commit again.

Amend and skip hooks

Two checkboxes under the commit message change what the buttons do:

• Amend previous commit replaces the last commit with the staged changes and the new message. The buttons become Amend and Amend & Push. Amending a commit that is already on the remote needs an explicit force push with lease.
• Skip hooks commits without running the repository's pre-commit and commit-msg hooks, like git commit --no-verify. Other hooks, such as prepare-commit-msg and post-commit, still run. Commit & Push then also skips the pre-push hook. The buttons show the choice, for example Commit without Hooks or Amend & Push without Hooks.

Skip hooks stays on for later commits in the same window until you turn it off. It is never saved, so a new window always runs hooks. The toolbar's Push always runs hooks.

Git LFS uploads file content from its pre-push hook. When Commit & Push skips that hook and the commits it publishes contain LFS files, GitComet runs git lfs push itself before pushing. If LFS content is missing, the push stops instead of publishing commits whose files the remote cannot serve.

See Reviewing Changes for partial staging, comparisons, previews, and blame.

Synchronize with a remote

Fetch downloads remote history so you can review incoming changes. Pull integrates remote changes into your current branch; GitComet offers merge, rebase, and fast-forward policies. Push publishes your local commits to the configured remote.

GitComet uses your Git authentication setup and can show credential, SSH passphrase, and host-verification prompts in the app. See SSH Keys for SSH remotes and Fetch, pull, and push for the differences between these operations.

In this section

• Reviewing Changes
• Git Basics
• SSH Keys
• SSH Keys for Git Hosts
• Abort or Undo a Merge