Quick start

This page takes you from an installed application to a pushed commit. The whole loop is four steps, and three of them are keyboard shortcuts.

Before you start

1. Confirm git --version works in a terminal. Gitwright uses the system Git binary; if it is not on PATH, set the path in Settings → Git.
2. Have a repository ready, locally or as a clone URL.
3. Optional: install git-lfs if the repository uses large file storage.

Step 1 — Open a repository

• Press Cmd/Ctrl + O, or use File → Open Repository.
• For a new copy, use File → Clone and paste the remote URL.
• Repositories you opened before appear in the recent list and in the Workspace dashboard.

The workbench opens with five tabs: Files, Changes, History, Branches and Stashes. The right side shows the commit composer and sync controls.

Step 2 — Stage what you changed

1. Open Changes (Cmd/Ctrl + 2).
2. Select a file and press Space to stage the whole file.
3. To stage part of a file, select a hunk or a set of lines in the diff and press Space again.

Staging is bound to the diff you are looking at. If the file changes on disk between the read and the stage — an editor save, a formatter, a Git hook — the stage is rejected, the index is not touched, and the diff reloads. The notice says the diff was stale; re-read it and stage again.

Step 3 — Commit

1. Type a message in the commit composer.
2. Press Cmd/Ctrl + Enter.

The commit runs against the staged content only. Untracked files that are not staged stay untracked. Files that had staged and unstaged changes keep the unstaged part in the working tree.

If you want a draft first, the assistant can propose a message from the staged diff. It only fills the message box; the commit still runs when you press the shortcut. See ACP agents.

Step 4 — Sync

• Cmd/Ctrl + Shift + P pushes the current branch. The first push of a branch without an upstream asks which remote branch to create.
• Fetch and Pull sit next to Push in the workbench.
• Pull behaviour (merge, rebase, fast-forward only) is set once in Settings → Git.

If the push is rejected because the remote moved, fetch, inspect the divergence, and decide. A forced push is available but always requires a lease and writes a recovery snapshot of the remote-tracking tip first. See Sync.

The keyboard path

The full map, including window and file shortcuts, is in Shortcuts.

Where things are

Next steps

• Changes — per-line staging, batch outcomes and discards.
• History — graph, blame, rebase and cherry-pick.
• Recovery — what a snapshot contains and how to restore it.
• Troubleshooting — missing Git, stuck locks, huge repositories.