devel/GitGerrit.mdwn

   1 git-gerrit
   2 ==========
   3
   4 **git-gerrit** is command line tool for the [Gerrit code review system][1], with an
   5 emphasis on the Gerrit legacy numerical identifiers.  The heavy lifting is done
   6 with the **pygerrit2** package to access the Gerrit REST API.
   7 **git-gerrit** is compatible with Python 2 and Python 3.
   8
   9 Commands::
  10
  11     git gerrit-help              List commands.
  12     git gerrit-query             Search gerrit.
  13     git gerrit-fetch             Fetch by gerrit number.
  14     git gerrit-checkout          Fetch then checkout by gerrit number.
  15     git gerrit-log               Show oneline log with gerrit numbers.
  16     git gerrit-unpicked          Find gerrit numbers on upstream branch not cherry picked.
  17     git gerrit-cherry-pick       Cherry pick from upstream branch by gerrit number.
  18     git gerrit-install-hooks     Install git hooks to create gerrit change-ids.
  19
  20 Installation
  21 ============
  22
  23 Install with pip::
  24
  25     $ pip install --user git-gerrit
  26
  27 To install from source, clone the git repo and install with the provided
  28 makefile.  `make` will run `pip` to install the package and
  29 requirements::
  30
  31     $ git clone https://github.com/meffie/git-gerrit.git
  32     $ cd git-gerrit
  33     $ make install
  34
  35 Clone the git project under gerrit review, and in that project directory
  36 set the Gerrit host and project names in the local git configuration::
  37
  38     $ cd <your-gerrit-project>
  39     $ git config gerrit.host <gerrit-hostname>
  40     $ git config gerrit.project <gerrit-project>
  41
  42 Finally, download the git hook provided by gerrit and a git hook provided
  43 by git-gerrit::
  44
  45     $ git gerrit-install-hooks
  46
  47 Examples
  48 ========
  49
  50 Setup a local OpenAFS git repo::
  51
  52     $ git clone git://git.openafs.org/openeafs.git # (if not already cloned)
  53     $ cd openafs
  54     $ git config --local gerrit.host gerrit.openafs.org
  55     $ git config --local gerrit.project openafs
  56     $ git gerrit-install-hooks
  57
  58 Find open gerrits on the master branch::
  59
  60     $ git gerrit-query -n3 is:open branch:master
  61     13030 redhat: Make separate debuginfo for kmods work with recent rpm
  62     13031 redhat: PACKAGE_VERSION macro no longer exists
  63     13021 autoconf: update curses.m4
  64
  65 Find gerrits with subjects containing the term 'debuginfo'::
  66
  67     $ git gerrit-query -n3 debuginfo
  68     13030 redhat: Make separate debuginfo for kmods work with recent rpm
  69     13029 redhat: Create unique debuginfo packages for kmods
  70     12818 redhat: separate debuginfo package for kmod rpm
  71
  72 Also show the branch name::
  73
  74     $ git gerrit-query -n3 --format='{branch:>20s} {_number} {subject}' debuginfo
  75                   master 13030 redhat: Make separate debuginfo for kmods work with recent rpm
  76     openafs-stable-1_6_x 13029 redhat: Create unique debuginfo packages for kmods
  77     openafs-stable-1_6_x 12818 redhat: separate debuginfo package for kmod rpm
  78
  79 List the gerrit topics on a branch::
  80
  81     $ git gerrit-query --format='{topic}' status:open branch:master | sort -u | head -n3
  82     afsd-cache-verify
  83     AFS-OSD-integration
  84     afs_read-EOF
  85
  86 Show gerrit submissions on the master branch I need to review::
  87
  88     $ git gerrit-query branch:master status:open NOT label:Code-Review=-2 NOT reviewer:tycobb@yoyodyne.com
  89     ...
  90
  91 Fetch a gerrit by number::
  92
  93     $ git gerrit-fetch 12977
  94
  95 Checkout a gerrit by number::
  96
  97     $ git gerrit-checkout 13000
  98
  99 Cherry-pick a gerrit onto the current branch::
 100
 101     $ git gerrit-fetch --no-branch 13001 && git cherry-pick FETCH_HEAD
 102
 103 Show gerrit numbers in one the checked out branch::
 104
 105     $ git gerrit-log -n3
 106     12958 f47cb2d Suppress statement not reached warnings under Solaris Studio
 107     12957 306f0f3 afs: squash empty declaration warning
 108     12955 e006609 libafs: git ignore build artifacts on Solaris
 109
 110 Show gerrit numbers by a revision::
 111
 112     $ git gerrit-log -n3 openafs-stable-1_8_0
 113     12953 a08327f Update NEWS for 1.8.0 final release
 114     12938 acb0e84 afs_pioctl: avoid -Wpointer-sign
 115     12950 b73863b LINUX: fix RedHat 7.5 ENOTDIR issues
 116
 117 Show gerrit numbers by a range of revisions::
 118
 119     $ git gerrit-log 607eba34d..origin/openafs-stable-1_8_x
 120     13268 554176bd2 LINUX: Update to Linux struct iattr->ia_ctime to timespec64 with 4.18
 121     13266 eb107ed5c Make OpenAFS 1.8.1
 122     13265 8de978420 Update NEWS for 1.8.1
 123
 124 Show just the gerrit numbers and subjects::
 125
 126     $ git gerrit-log -n3 --format='{number}: {subject}'
 127     12958: Suppress statement not reached warnings under Solaris Studio
 128     12957: afs: squash empty declaration warning
 129     12955: libafs: git ignore build artifacts on Solaris
 130
 131 Show the commits on the master branch which have not been cherry-picked on to
 132 the stable branch. (Gerrits may already exists for them.)::
 133
 134     $ git gerrit-unpicked -u origin/master origin/openafs-stable-1_8_x
 135     13656 4eeed830fa31b7b8b5487ba619acbc8d30642aaa afscp: Link against opr/roken/hcrypto
 136     13659 f5f59cd8d336b153e2b762bb7afd16e6ab1b1ee2 util: serverLog using memory after free
 137     13665 1210a8d6d96db2d84595d35ef81ec5d176de05e8 LINUX: Run the 'sparse' checker if available
 138     ...
 139
 140
 141 Using git aliases
 142 =================
 143
 144 Commonly used queries can be saved as git aliases. For example to show the
 145 gerrits which have not been reviewed yet::
 146
 147     [alias]
 148     # git gerrit-todo [<branch>] [<userid>]
 149     gerrit-todo = "!f() { git-gerrit-query \"branch:${1-master} is:open NOT label:Code-Review>=+1,${2-$USER}\"; }; f"
 150
 151 Command help
 152 ============
 153
 154 Command git-gerrit-checkout::
 155
 156     usage: git-gerrit-checkout [-h] [--repodir REPODIR] <number>
 157
 158     Fetch then checkout by gerrit number.
 159
 160     positional arguments:
 161       <number>           legacy change number
 162
 163     optional arguments:
 164       -h, --help         show this help message and exit
 165       --repodir REPODIR  path to the git project directory
 166
 167 Command git-gerrit-cherry-pick::
 168
 169     usage: git-gerrit-cherry-pick [-h] [-b <branch>] <number>
 170
 171     Cherry pick from upstream branch by gerrit number.
 172
 173     positional arguments:
 174       <number>              legacy change number
 175
 176     optional arguments:
 177       -h, --help            show this help message and exit
 178       -b <branch>, --branch <branch>
 179                             upstream branch (default: origin/master)
 180
 181     Note: A new gerrit Change-Id will be created in the cherry-picked commit.
 182
 183     Example usage:
 184
 185         $ git gerrit-query is:merged branch:master 'fix the frobinator'
 186         1234 fix the frobinator
 187
 188         $ git fetch origin
 189         $ git checkout -b fix origin/the-stable-branch
 190         ...
 191
 192         $ git gerrit-cherry-pick 1234 -b origin/master
 193         [fix f378563c94] fix the frobinator
 194          Date: Fri Apr 4 10:27:10 2014 -0400
 195           2 files changed, 37 insertions(+), 12 deletions(-)
 196
 197         $ git push gerrit HEAD:refs/for/the-stable-branch
 198         ...
 199
 200 Command git-gerrit-fetch::
 201
 202     usage: git-gerrit-fetch [-h] [--repodir REPODIR] [--checkout] [--no-branch]
 203                             <number>
 204
 205     Fetch by gerrit number.
 206
 207     positional arguments:
 208       <number>           legacy change number
 209
 210     optional arguments:
 211       -h, --help         show this help message and exit
 212       --repodir REPODIR  path to the git project directory
 213       --checkout         checkout after fetch
 214       --no-branch        do not create a local branch
 215
 216 Command git-gerrit-help::
 217
 218
 219     Commands for gerrit code review:
 220
 221         git gerrit-help              List commands.
 222         git gerrit-query             Search gerrit.
 223         git gerrit-fetch             Fetch by gerrit number.
 224         git gerrit-checkout          Fetch then checkout by gerrit number.
 225         git gerrit-log               Show oneline log with gerrit numbers.
 226         git gerrit-unpicked          Find gerrit numbers on upstream branch not cherry picked.
 227         git gerrit-cherry-pick       Cherry pick from upstream branch by gerrit number.
 228         git gerrit-install-hooks     Install git hooks to create gerrit change-ids.
 229
 230     Show command details with:
 231
 232         git gerrit-<command> -h
 233
 234 Command git-gerrit-install-hooks::
 235
 236     usage: git-gerrit-install-hooks [-h]
 237
 238     Install git hooks to create gerrit change-ids.
 239
 240     optional arguments:
 241       -h, --help  show this help message and exit
 242
 243 Command git-gerrit-log::
 244
 245     usage: git-gerrit-log [-h] [--repodir REPODIR] [--format FORMAT] [-n NUMBER]
 246                           [-r] [-l]
 247                           [revision]
 248
 249     Show oneline log with gerrit numbers.
 250
 251     positional arguments:
 252       revision              revision range
 253
 254     optional arguments:
 255       -h, --help            show this help message and exit
 256       --repodir REPODIR     path to the git project directory
 257       --format FORMAT       output format (default: "{number} {hash} {subject}")
 258       -n NUMBER, --number NUMBER
 259                             number of commits
 260       -r, --reverse         reverse order
 261       -l, --long-hash       show full sha1 hash
 262
 263     format fields: number, hash, subject
 264
 265 Command git-gerrit-query::
 266
 267     usage: git-gerrit-query [-h] [--repodir REPODIR] [-n LIMIT] [--format FORMAT]
 268                             [--dump] [--details]
 269                             <term> [<term> ...]
 270
 271     Search gerrit.
 272
 273     positional arguments:
 274       <term>                search term
 275
 276     optional arguments:
 277       -h, --help            show this help message and exit
 278       --repodir REPODIR     path to the git project directory
 279       -n LIMIT, --number LIMIT
 280                             limit the number of results
 281       --format FORMAT       output format string
 282       --dump                dump data
 283       --details             get extra details
 284
 285 Command git-gerrit-unpicked::
 286
 287     usage: git-gerrit-unpicked [-h] [-u UPSTREAM_BRANCH] downstream_branch
 288
 289     Find gerrit numbers on upstream branch not cherry picked.
 290
 291     positional arguments:
 292       downstream_branch     downstream branch name
 293
 294     optional arguments:
 295       -h, --help            show this help message and exit
 296       -u UPSTREAM_BRANCH, --upstream-branch UPSTREAM_BRANCH
 297                             upstream branch name
 298
 299
 300
 301 See Also
 302 ========
 303
 304 See the [git-review][2] project for a more complete git/gerrit workflow tool.
 305
 306
 307 [1]: https://www.gerritcodereview.com/
 308 [2]: https://www.mediawiki.org/wiki/Gerrit/git-review