Keywords: Gerrit | Git Push | Code Review
Abstract: This article provides an in-depth analysis of why git push gerrit HEAD:refs/for/master is used instead of git push origin master in the Gerrit code review system. By explaining Gerrit's internal mechanisms, it covers the magical refs/for/<BRANCH> namespace, how Gerrit manages code review through database updates and custom SSH/Git stacks, and offers configuration simplifications and tool integration tips to help developers effectively use Gerrit.
How the Gerrit Code Review System Works
In the Gerrit code review system, the standard Git push command git push origin master is rejected with an error message: ! [remote rejected] master -> master (prohibited by Gerrit). This is because Gerrit enforces a unique code review workflow that requires developers to push changes to the specific refs/for/<BRANCH> namespace instead of directly to branches.
The Magic of refs/for/<BRANCH>
Gerrit implements its own Git and SSH stacks to provide the so-called "magical" refs/for/<BRANCH> refs. When a push request is received to create a ref in these namespaces, Gerrit performs internal logic to update its database and lies to the client about the operation's result. A successful outcome makes the client believe that Gerrit has created the ref, but in reality, no ref is created. This mechanism allows Gerrit to stage changes in the "Pending Changes" area rather than merging them directly into the authoritative repository.
Detailed Code Review Process
The push command git push gerrit HEAD:refs/for/master sends the current commit (HEAD) to Gerrit's refs/for/master ref. This places the changes into the staging area for pending changes, where they await code review. After a successful review, Gerrit automatically pushes the changes from the staging area to the appropriate branch in the authoritative repository, based on the branch information specified during the push. This workflow ensures that only reviewed code enters the main codebase, maintaining code quality.
Configuration Simplification and Tool Integration
To simplify the push command, you can modify the Git configuration file. For example, add the following configuration: [remote "gerrit"] url = https://your.gerrit.repo:44444/repo fetch = +refs/heads/master:refs/remotes/origin/master push = refs/heads/master:refs/for/master After configuration, you can simply run git push gerrit to complete the push. Additionally, tools like Magit support pushing to Gerrit via custom functions or built-in commands, such as using P r "origin" RET "HEAD:refs/for/master" or installing dedicated packages like magit-gerrit for enhanced integration.
Core Advantages and Best Practices
The advantage of using refs/for/<BRANCH> over direct pushing is that it enforces code review, preventing unreviewed code from entering the main branch. Developers should familiarize themselves with Gerrit's documentation, properly configure remote repositories, and leverage tools to automate common tasks. By understanding the internal mechanisms, teams can use Gerrit more efficiently for collaboration and code quality management.