github.com/golang/review@v0.0.0-20190122205339-266ee1edf5c3/git-codereview/doc.go (about) 1 // Copyright 2014 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 /* 6 Git-codereview manages the code review process for Git changes using a Gerrit 7 server. 8 9 The git-codereview tool manages ``change branches'' in the local git repository. 10 Each such branch tracks a single commit, or ``pending change'', 11 that is reviewed using a Gerrit server; the Gerrit remote must be 12 named ``origin'' in the local git repo. 13 14 Modifications to the pending change are applied by amending the commit. 15 This process implements the ``single-commit feature branch'' model. 16 Creating multiple-commit feature branches, for example to break a large 17 change into a reviewable sequence, is also supported; see the discussion below. 18 19 Once installed as git-codereview, the tool's commands are available through git 20 either by running 21 22 git codereview <command> 23 24 or, if aliases are installed, as 25 26 git <command> 27 28 The review tool's command names do not conflict with any extant git commands. 29 This document uses the first form for clarity but most users install these 30 aliases in their .gitconfig file: 31 32 [alias] 33 change = codereview change 34 gofmt = codereview gofmt 35 mail = codereview mail 36 pending = codereview pending 37 rebase-work = codereview rebase-work 38 submit = codereview submit 39 sync = codereview sync 40 41 Single-Commit Work Branches 42 43 For simple, unrelated changes, the typical usage of the git-codereview tool 44 is to place each pending change in its own Git branch. 45 In this workflow, the work branch contains 46 either no pending change beyond origin/master (when there's no local work) 47 or exactly one pending change beyond origin/master (the change being developed). 48 49 When there is no pending change on the work branch, 50 ``git codereview change'' creates one by running ``git commit''. 51 Otherwise, when there is already a pending change, 52 ``git codereview change'' revises it by running ``git commit --amend''. 53 54 The ``git codereview mail'' and ``git codereview submit'' commands 55 implicitly operate on the lone pending change. 56 57 Multiple-Commit Work Branches 58 59 Of course, it is not always feasible to put each pending change in a separate branch. 60 A sequence of changes that build on one another is more easily 61 managed as multiple commits on a single branch, and the git-codereview tool 62 supports this workflow as well. 63 To add a new pending change, invoke ``git commit'' directly, 64 instead of ``git codereview change''. 65 The git-codereview tool adjusts its behavior when there are 66 multiple pending changes. 67 68 The ``git codereview change'' command amends the top commit in the stack (HEAD). 69 To amend a commit further down the stack, use Git's rebase support, 70 for example by using ``git commit --fixup'' followed by ``git codereview rebase-work''. 71 72 The ``git codereview mail'' command requires an explicit revision argument, 73 but note that since ``git codereview mail'' is implemented as a ``git push'', 74 any commits earlier in the stack are necessarily also mailed. 75 76 The ``git codereview submit'' command also requires an explicit revision argument, 77 and while earlier commits are necessarily still uploaded and mailed, 78 only the named revision or revisions are submitted (merged into origin/master). 79 In a single-commit work branch, a successful ``git codereview submit'' 80 effectively runs ``git codereview sync'' automatically. 81 In a multiple-commit work branch, it does not, because 82 the implied ``git rebase'' may conflict with the remaining pending commits. 83 Instead it is necessary to run ``git codereview sync'' explicitly 84 (when ready) after ``git codereview submit''. 85 86 Reusing Work Branches 87 88 Although one common practice is to create a new branch for each pending change, 89 running ``git codereview submit'' (and possibly ``git codereview sync'') 90 leaves the current branch ready for reuse with a future change. 91 Some developers find it helpful to create a single work branch 92 (``git change work'') and then do all work in that branch, 93 possibly in the multiple-commit mode, never changing between branches. 94 95 Command Details 96 97 All commands accept these global flags: 98 99 The -v flag prints all commands that make changes. Multiple occurrences 100 trigger more verbosity in some commands, including sync. 101 102 The -n flag prints all commands that would be run, but does not run them. 103 104 Descriptions of each command follow. 105 106 Branchpoint 107 108 The branchpoint command prints the commit hash of the most recent commit 109 on the current branch that is shared with the Gerrit server. 110 111 git codereview branchpoint 112 113 This commit is the point where local work branched from the published tree. 114 The command is intended mainly for use in scripts. For example, 115 ``git diff $(git codereview branchpoint)'' or 116 ``git log $(git codereview branchpoint)..HEAD''. 117 118 Change 119 120 The change command creates and moves between Git branches and maintains the 121 pending changes on work branches. 122 123 git codereview change [-a] [-q] [-m <message>] [branchname] 124 125 Given a branch name as an argument, the change command switches to the named 126 branch, creating it if necessary. If the branch is created and there are staged 127 changes, it will commit the changes to the branch, creating a new pending 128 change. 129 130 With no argument, the change command creates a new pending change from the 131 staged changes in the current branch or, if there is already a pending change, 132 amends that change. 133 134 The -q option skips the editing of an extant pending change's commit message. 135 If -m is present, -q is ignored. 136 137 The -a option automatically adds any unstaged edits in tracked files during 138 commit; it is equivalent to the 'git commit' -a option. 139 140 The -m option specifies a commit message and skips the editor prompt. This 141 option is only useful when creating commits (e.g. if there are unstaged 142 changes). If a commit already exists, it is overwritten. If -q is also 143 present, -q will be ignored. 144 145 Gofmt 146 147 The gofmt command applies the gofmt program to all files modified in the 148 current work branch, both in the staging area (index) and the working tree 149 (local directory). 150 151 git codereview gofmt [-l] 152 153 The -l option causes the command to list the files that need reformatting but 154 not reformat them. Otherwise, the gofmt command reformats modified files in 155 place. That is, files in the staging area are reformatted in the staging area, 156 and files in the working tree are reformatted in the working tree. 157 158 Help 159 160 The help command displays basic usage instructions. 161 162 git codereview help 163 164 Hooks 165 166 The hooks command installs the Git hooks to enforce code review conventions. 167 168 git codereview hooks 169 170 The pre-commit hook checks that all Go code is formatted with gofmt and that 171 the commit is not being made directly to the master branch. 172 173 The commit-msg hook adds the Gerrit ``Change-Id'' line to the commit message if 174 not present. It also checks that the message uses the convention established by 175 the Go project that the first line has the form, pkg/path: summary. 176 177 The hooks command will not overwrite an existing hook. 178 If it is not installing hooks, use ``git codereview hooks -v'' for details. 179 This hook installation is also done at startup by all other git codereview 180 commands, except ``git codereview help''. 181 182 Hook-Invoke 183 184 The hook-invoke command is an internal command that invokes the named Git hook. 185 186 git codereview hook-invoke <hook> [args] 187 188 It is run by the shell scripts installed by the ``git codereview hooks'' command. 189 190 Mail 191 192 The mail command starts the code review process for the pending change. 193 194 git codereview mail [-f] [-r email] [-cc email] [-trybot] [revision] 195 196 It pushes the pending change commit in the current branch to the Gerrit code 197 review server and prints the URL for the change on the server. 198 If the change already exists on the server, the mail command updates that 199 change with a new changeset. 200 201 The -r and -cc flags identify the email addresses of people to do the code 202 review and to be CC'ed about the code review. 203 Multiple addresses are given as a comma-separated list. 204 205 An email address passed to -r or -cc can be shortened from name@domain to name. 206 The mail command resolves such shortenings by reading the list of past reviewers 207 from the git repository log to find email addresses of the form name@somedomain 208 and then, in case of ambiguity, using the reviewer who appears most often. 209 210 The -trybot flag runs the trybots on all new or updated changes. It is 211 equivalent to setting the Run-Trybot+1 label from Gerrit. 212 213 The mail command fails if there are staged edits that are not committed. 214 The -f flag overrides this behavior. 215 216 The mail command updates the tag <branchname>.mailed to refer to the 217 commit that was most recently mailed, so running ``git diff <branchname>.mailed'' 218 shows diffs between what is on the Gerrit server and the current directory. 219 220 If there are multiple pending commits, the revision argument is mandatory. 221 If no revision is specified, the mail command prints a short summary of 222 the pending commits for use in deciding which to mail. 223 224 If any commit that would be pushed to the server contains the text 225 "DO NOT MAIL" (case insensitive) in its commit message, the mail command 226 will refuse to send the commit to the server. 227 228 Pending 229 230 The pending command prints to standard output the status of all pending changes 231 and staged, unstaged, and untracked files in the local repository. 232 233 git codereview pending [-c] [-l] [-s] 234 235 The -c flag causes the command to show pending changes only on the current branch. 236 237 The -l flag causes the command to use only locally available information. 238 By default, it fetches recent commits and code review information from the 239 Gerrit server. 240 241 The -s flag causes the command to print abbreviated (short) output. 242 243 Common shorter aliases include ``git p'' for ``git pending'' 244 and ``git pl'' for ``git pending -l'' (notably faster but without Gerrit information). 245 246 Rebase-work 247 248 The rebase-work command runs git rebase in interactive mode over pending changes. 249 It is shorthand for ``git rebase -i $(git codereview branchpoint)''. 250 It differs from plain ``git rebase -i'' in that the latter will try to incorporate 251 new commits from the origin branch during the rebase; 252 ``git codereview rebase-work'' does not. 253 254 In multiple-commit workflows, rebase-work is used so often 255 that it can be helpful to alias it to ``git rw''. 256 257 Submit 258 259 The submit command pushes the pending change to the Gerrit server and tells 260 Gerrit to submit it to the master branch. 261 262 git codereview submit [-i | revision...] 263 264 The command fails if there are modified files (staged or unstaged) that are not 265 part of the pending change. 266 267 The -i option causes the submit command to open a list of commits to submit 268 in the configured text editor, similar to ``git rebase -i''. 269 270 If multiple revisions are specified, the submit command submits each one in turn, 271 stopping at the first failure. 272 273 When run in a multiple-commit work branch, 274 either the -i option or the revision argument is mandatory. 275 If both are omitted, the submit command prints a short summary of 276 the pending commits for use in deciding which to submit. 277 278 After submitting the pending changes, the submit command tries to synchronize the 279 current branch to the submitted commit, if it can do so cleanly. 280 If not, it will prompt the user to run ``git codereview sync'' manually. 281 282 After a successful sync, the branch can be used to prepare a new change. 283 284 Sync 285 286 The sync command updates the local repository. 287 288 git codereview sync 289 290 It fetches commits from the remote repository and merges them from the 291 upstream branch to the current branch, rebasing any pending changes. 292 293 Configuration 294 295 If a file named codereview.cfg is present in the repository root, 296 git-codereview will use it for configuration. It should contain lines 297 of this format: 298 299 key: value 300 301 The ``gerrit'' key sets the Gerrit URL for this project. Git-codereview 302 automatically derives the Gerrit URL from repositories hosted in 303 *.googlesource.com. If not set or derived, the repository is assumed to 304 not have Gerrit, and certain features won't work. 305 306 The ``issuerepo'' key specifies the GitHub repository to use for issues, if 307 different from the source repository. If set to ``golang/go'', for example, 308 lines such as ``Fixes #123'' in a commit message will be rewritten to ``Fixes 309 golang/go#123''. 310 311 */ 312 package main