Getting started / TutorialMarkdown

Tutorial

Fifteen minutes with grit. Create a repository, record some changes, work on a branch, and share it with a remote.

This walkthrough covers the commands you'll use every day. It assumes you have installed grit and know roughly what a commit and a branch are. The output shown is what grit prints, minus the colors.

Regenerated on 2026-10-07 by running the listed commands with grit built from this repository (cargo build --release -p grit-cli), with NO_COLOR=1 and author identity Ada Lovelace <ada@example.com>.

Tell grit who you are

Every commit records an author. Set your name and email once, in your global config:

grit reads and writes the same config files as Git, so if you've already set these up for Git, you can skip this step.

$ grit config --global user.name "Ada Lovelace"
$ grit config --global user.email ada@example.com

Create a repository

To work on an existing project instead, copy it with grit clone and skip ahead to the next section:

$ grit init project
Initialized empty repository in /workspace/project/.git
$ cd project

$ grit clone https://github.com/gitbutlerapp/grit.git

Your home base: grit status

Running grit with no arguments shows where you are and what's changed. Add a couple of files and look:

The last line always suggests the next step. You'll come back to this screen a lot; grit status (or grit st) shows the same thing.

$ echo "# Notes" > README.md
$ echo "fn main() {}" > main.rs
$ grit
On main — no commits yet

Untracked
  ?  untracked     README.md
  ?  untracked     main.rs

→ grit add <file> to stage

Record a commit

grit commit stages every change in the working tree and records it in one step:

There is no separate staging step to remember. grit add exists for when you want to stage particular files and check them in grit status first, but grit commit always records every change.

$ grit commit "Start the project"
[main 310fdb0] Start the project
2 changes committed

Look at the history with grit log

$ grit log
  310fdb0  ada  just now  Start the project

Work on a branch

Make a change and look at it with grit diff before committing:

The two number columns are the old and new line numbers. Commit the change:

grit show displays a commit, its message and the files it changed. With no argument, it shows the latest commit:

Create a branch and switch to it with grit switch -c

$ grit switch -c feature
Created and switched to branch feature

$ printf 'fn main() {\n    println!("hi");\n}\n' > main.rs
$ grit diff

main.rs
@@ -1 +1 @@
 1    │ - fn main() {}
    1 │ + fn main() {
    2 │ +     println!("hi");
    3 │ + }

$ grit commit "Say hi"
[feature 2e409e2] Say hi
1 change committed

$ grit show
branch feature
commit 2e409e26f8b370ea1928a8fb93dcf2e025418e1f
Author: Ada Lovelace <ada@example.com>
Date:   2026-10-07 14:55:47 +0000

    Say hi

 main.rs |   4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

Merge it back

Switch back to main and merge the branch in. Nothing else has happened on main, so grit just moves main forward:

grit branch -d refuses to delete a branch whose commits haven't been merged into the branch you're on. Use -D when you really mean it.

$ grit switch main
Switched to branch main
$ grit merge feature
Fast-forwarded feature → 2e409e2

The branch is done, so delete it

$ grit branch -d feature
Deleted branch feature (was 2e409e2).

A remote is another copy of the repository, usually on a server. Add one called origin with grit remote add, then push:

grit push sends the current branch to a branch with the same name on origin, creating it if needed. There are no upstream flags to set. For GitHub over HTTPS, grit auth signs you in, and grit offers to run it if a push fails for lack of credentials.

To get other people's work, run grit pull. It fetches from the remote and brings your branch up to date, fast-forwarding when it can and recording a merge commit when both sides have new commits:

If someone pushed before you, grit push is rejected and tells you what to do:

$ grit remote add origin https://github.com/ada/project.git
Added remote origin → https://github.com/ada/project.git
$ grit push
  pushed main → origin refs/heads/main

$ grit pull
Merged origin/main into the current branch (91275a2)

$ grit push
  rejected origin refs/heads/main: not a fast-forward — run `grit pull` first

Tag a release

grit tag marks the current commit, and grit push --tags publishes your tags:

$ grit tag v0.1
Created tag v0.1
$ grit push --tags
  pushed --tags → origin refs/tags/v0.1

When things conflict

grit merge, grit pull and grit pick never leave a half-finished merge behind. If the two sides change the same lines, grit lists the conflicting files and leaves your branch and working tree as they were. To resolve the conflict, run the merge with git, fix the files and commit. Conflict resolution in grit itself is on the roadmap.

grit also refuses to switch branches, merge or pull while you have uncommitted changes, so work in progress can't get mixed into a merge. Commit first.

Scripting

Every command takes --json and prints a single JSON object, which is handy for scripts and agents. --filter picks out the part you need:

See Scripting with grit for details, and each command's page for its JSON fields.

$ grit status --json --filter '{branch, clean}'
{
  "branch": "main",
  "clean": true
}

Where to go next

Every command has a man page with its options and examples. Start from the command list.