# google/git-appraise: code review stored as Git notes, no server required

> Git Appraise keeps review requests, comments and CI results inside the repository as git-notes objects, so any Git host can carry a review workflow. The trade-off is a client that has seen no push since 2021-04-22.

**google/git-appraise** — GitHub describes it as Distributed code review system for Git repos. The repository metadata lists Go as its primary language. The metadata lists the Apache-2.0 license. This article stays within the project description and details documented in the GitHub repository README.

- Repository: https://github.com/google/git-appraise
- Stars: 5,322 · Forks: 148
- Language: Go
- License: Apache-2.0
- Published: 2026-08-13 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/google-git-appraise

## The problem: review state that lives outside the repository

Most review tools keep the conversation on a server. The diff is in Git, the comments are in a database, and the two drift apart the moment someone force-pushes or the service is retired. Git Appraise inverts that. The README describes it as a distributed code review system: review requests, human comments, robot comments from static analysis, and CI results are all written into the repository as git objects. The stated consequence is that no server-side setup is needed, the tool works with any Git hosting provider, and the only installation step is the client on a workstation.

The audience is narrow and specific. It fits teams that already treat a Git remote as the shared source of truth and are willing to run a command-line review flow. It does not fit anyone who wants a browser dashboard maintained by the project itself. The README lists a separate graphical interface, Git-Appraise-Web, as an integration rather than part of this repository, so the CLI is the product here.

## How review data is stored: four refs under refs/notes/devtools

The mechanism is git-notes. Each metadata item is a single line of JSON, with at most one item per line, which is what allows the notes to be merged automatically using the cat_sort_uniq strategy. Refs all begin with the prefix refs/notes/devtools so it is obvious they are written by tools rather than people.

The README assigns each kind of data its own ref and schema. Review requests go to refs/notes/devtools/reviews and annotate the first revision in a review. CI build and test results go to refs/notes/devtools/ci and annotate the revision that was built. Robot comments from static analysis tools go to refs/notes/devtools/analyses. Human comments go to refs/notes/devtools/discuss and annotate the first revision in the review. A field named v records the metadata format version and defaults to 0 when absent.

One detail matters more than the rest. If a commit carries multiple review requests, they are sorted by timestamp and the final one is treated as current, with stable sorting so that equal timestamps resolve to the last request in the note. That is what lets a user update a request by re-running git appraise request instead of editing history. It also means timestamps are load-bearing: two machines with skewed clocks can disagree about which request wins, and the resolution is silent.

## Installing git-appraise and running a first review

The README assumes the Go tools are installed, then gives a single install command. It builds the binary into your Go binary directory.

```bash
go install github.com/google/git-appraise/git-appraise@latest
```

Next it asks you to either put ${GOPATH}/bin on your PATH or register a Git alias so the tool is reachable as git appraise. The alias form is the one the rest of the usage examples assume.

```bash
git config --global alias.appraise '!'"${GOPATH}/bin/git-appraise"
```

On Windows the README gives a different quoting form for the same alias.

```bash
git config --global alias.appraise "!%GOPATH%/bin/git-appraise.exe"
```

The stated requirements are short: the git command line tool must be installed and on the PATH, the tool must be run from inside a Git repo, and git must already hold the credentials needed to push to and pull from the remotes. Nothing else is configured.

With that in place, the first real use is to open a review on the current branch, then list and inspect it.

```bash
git appraise request
git appraise list
git appraise show
git appraise show --diff
```

request writes a review request note for the first revision. list prints the open reviews, show prints the status of the current review including comments, and show --diff adds the diff, with an optional --diff-opts "<diff-options>" passthrough. A reviewer replies with git appraise comment -m "<message>", optionally scoped with -f <file> and -l <line>, then accepts with git appraise accept. The author finishes with git appraise submit, choosing either --merge or --rebase. Reviews move between machines with git appraise push [<remote>] and git appraise pull [<remote>]; the README states that updates from the remote are merged automatically on pull. A longer getting started document lives at docs/tutorial.md.

## Where the distributed model gets awkward

The design pushes complexity onto Git itself. Reviews live in refs that are not fetched by default in most workflows, so a reviewer who runs a plain git fetch may see nothing new. The README does not document a fetch refspec for refs/notes/devtools/*, which means the plumbing is left to the user.

Automatic merging is the second soft spot. The cat_sort_uniq strategy keeps concurrent note edits from conflicting, but it works because each item is one JSON line. That is a real constraint on anything built on top: a tool that wants to store multi-line JSON in these refs breaks the merge property. The README states the one-item-per-line rule plainly, and it reads as a design boundary rather than a formatting preference.

There is also no access control layer to configure, because there is no server. Whoever can push to the repository can push review notes. If your process depends on approvals that a central system enforces, Git Appraise records the approval but does not gate the merge. The README describes accept and submit as commands a person runs, not as checks a host enforces.

## Git Appraise compared with Gerrit

Gerrit is the obvious point of comparison, and the difference is architectural rather than cosmetic. Gerrit runs a server that owns the review database, serves a web interface, and gates submission through its own refs and permissions model. Git Appraise has no server component at all: the README says the only setup required is the client, and the review history is copied to every developer, who pushes and pulls it like any other object.

That changes what you have to operate. With Gerrit you maintain a service, its storage and its upgrade path. With Git Appraise you maintain nothing, but you also get nothing that a service provides: no hosted web UI in this repository, no central permission model, and no built-in merge gate. The README points to Git-Appraise-Web for a graphical interface and to mirror projects for GitHub pull requests and Phabricator revisions, which is an admission that many teams will want a bridge to a system that does have a UI.

## Maintenance, releases and the Apache-2.0 licence

The release history is thin and old. v0.7 is described as a rollup of the latest version as of April 2021 and is dated 2021-04-22, the same date as the last push to the default branch. The two releases before it, v0.6 and v0.5, are both dated 2016-09-21. So the project shipped two releases in 2016 and then nothing tagged until 2021. The repository is not archived, but the last push was on 2021-04-22, which is more than six months before today. Treat it as a stable, quiet codebase rather than one receiving regular changes.

The go.mod declares module github.com/google/git-appraise with go 1.18 and a single dependency, golang.org/x/sys. That is a small surface to audit and a small surface to keep current. Upgrading is therefore mostly about your Go toolchain rather than about churn in the project's own dependencies.

The licence is Apache-2.0, which permits commercial and private use and requires preservation of notices. Because review metadata is written into your own repository, the licence question that usually matters with a hosted review service, namely where your comment data sits, does not arise here. This is a description of the licence terms, not legal advice; check the LICENSE file and your own obligations.

## Conclusion

Adopt git-appraise if your team already pushes and pulls a shared Git remote, wants review metadata to travel with the objects rather than live behind a vendor API, and can carry a Go-built client that last saw a push on 2021-04-22. Do not adopt it if you need a web review UI out of the box, enforced merge gates, or a project with recent releases; the last tagged release is v0.7 from the same date. Before committing, verify that your Git host accepts pushes to refs/notes/devtools/*, that every reviewer can run go install github.com/google/git-appraise/git-appraise@latest against a Go toolchain, and that your notes merge strategy is set, because the tool's own merge behaviour depends on the cat_sort_uniq strategy described in the README.

## FAQ

### Why do people use Gerrit?

Gerrit runs a server that owns the review database, serves a web interface and gates submission through its own refs and permissions model, which is the opposite of the serverless approach Git Appraise takes.

### Can ChatGPT do a code review?

That is outside Git Appraise. The tool does record robot comments from static analysis tools, stored in the refs/notes/devtools/analyses ref under the analysis schema, but the README does not describe any language-model integration.

### What the heck is Git?

Git Appraise assumes you already know. Its stated requirements are that the git command line tool is installed and on the PATH, that the tool is run from inside a git repo, and that git holds the credentials for the remotes.

### Does Google still use Gerrit?

The README does not say. What it does show is that google/git-appraise is a Google-published distributed alternative whose review data lives in git-notes rather than in a Gerrit server.

## Sources

- [Official README](https://github.com/google/git-appraise#readme)
- [Project repository](https://github.com/google/git-appraise)
- [Release notes](https://github.com/google/git-appraise/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/google-git-appraise