View source for Using git-review to push and review changes

==Introduction==
This page explains how to use git-review to resolve manually merge conflicts in gerrit. Git-review is a tool, developed in Openstack Infra, to make easier the review process through command line. More details on git-review can be found [https://wiki.documentfoundation.org/Development/GitReview here]. Optionally, you can use git, as described in this [[Resolving merge conflicts|link]].

==Install and configure git review==
 $ sudo apt-get install git-review

Optionally, you could install it through pip:
 $ sudo apt-get install python-pip
 $ sudo easy_install pip
 $ sudo pip install git-review

Configure git-review. These options are required to work easily with OSM:
 $ git config --global gitreview.remote origin
 $ git config --global gitreview.username myusername
 $ git config --global gitreview.track true
 
==Prepare your repo==
For git-review to work properly, it is recommended to clone the repo via the SSH URL and to copy the commit-msg hook. If your user is "user" and the repo is the devops repo, the command would be:
 $ git clone ssh://user@osm.etsi.org:29418/osm/devops && scp -p -P 29418 user@osm.etsi.org:hooks/commit-msg devops/.git/hooks/

'''NOTE''': HTTP and HTTPS URLs might work by setting the variable gitreview.scheme to "http" or "https" respectively, although it has not been tested.

If you have your repo already cloned (e.g. devops), you can use the following commands to set SSH URL and get the commit-msg hook:
 $ cd devops
 $ git remote set-url origin ssh://user@osm.etsi.org:29418/osm/devops
 $ scp -p -P 29418 user@osm.etsi.org:hooks/commit-msg .git/hooks/

After cloning a repository, you need to set it up for git-review. This happens automatically the first time you submit a commit, but it's recommended to do it right after cloning.
 $ git review -s

==Push your changes to gerrit==
First, commit your files locally:
 <nowiki>
$ git add file2.txt
$ git commit -s -m "New file: file2"
[master b8efc98] New file: file2
 1 file changed, 1 insertion(+)
 create mode 100644 file2.txt
</nowiki>

Then push your commits to gerrit, with "git review -c".
 <nowiki>
$ git review -c
remote: Processing changes: new: 1, refs: 1, done
remote: Missing issue-id in commit message
remote: Commit b05fa3cf2a09cc6e27b14bed2c0403282ceba64d not associated to any issue
remote:
remote: Hint: insert one or more issue-id anywhere in the commit message.
remote:       Issue-ids are strings matching [Bb][Uu][Gg][ ]*([1-9][0-9]*)
remote:       and are pointing to existing tickets on its-bugzilla Issue-Tracker
remote:
remote: New Changes:
remote:   https://osm.etsi.org/gerrit/1267 New file: file2
remote:
To ssh://garciadeblas@osm.etsi.org:29418/test
 * [new branch]      HEAD -> refs/for/master
</nowiki>

'''Note''': The option -c is important because, otherwise, it won't work in OSM. The reason is that option "-c" makes pushes to refs/for/* instead of refs/publish/*, which allows to work with old versions of gerrit.
Current gerrit version in OSM can work with both refs/for and refs/publish, but branches have been created in refs/for. Migrating to refs/publish is a major effort, so we will have to keep the old approach until we can migrate.

==Amending a change==
First, download the change with git-review
 $ git review -d 1280
 Downloading refs/changes/80/1280/1 from gerrit
 Switched to branch "review/garciadeblas/1280"

This will download the change, put it in a branch called review/AUTHOR/change (if the change has no tag, the sequence number will be used instead), and switch to that branch.

After that, you can amend the downloaded change to improve it. Finally, push it again
 $ git add                         # add the changes
 $ git commit --amend              # do not touch the Change-Id. The Change-Id is the way for gerrit to keep track what belongs to what development stream as a new patch set.
 $ git commit --amend --author     # if you want to mark the changes as yours.
 $ git review -c -R                # The -R is important, since it tells git-review to not rebase your change against master.

'''NOTE''': Don't use the -m flag to specify a commit message, since it will override the previous message and regenerate the Change-Id. Instead, use the text editor to change the commit message if needed, and keep the Change-Id line intact.

==Git-review for administrators and reviewers==
Besides the previous commands, there are useful commands for reviewers (MDLs, TSC, etc.).

'''NOTE''': Option "-c" is always mandatory since we are using old schema for brnaches in gerrit.

===Listing open reviews===
 git review -l

===Submitting for review===
*To add a topic:
 git review -t topic/blablabla

*To add reviewers
 git review --reviewers john@aaa.com tracy@bbb.com

*To submit for review and then remove the local branch:
 git review -f

*To submit for review as a draft:
 git review -D

===Reviewing===
*To download a change using change number:
 git review -d 1200

*To download a specific patchset:
 git review -d 1200,2

*To compare two patches of the same change:
 git review -m 1200,2-5

===Scoring code review===
Git-review does not allow yet sending a -2/-1/+1/+2 for code review, and does not allow submitting a change. For that, you can use [https://review.openstack.org/Documentation/cmd-index.html gerrit command line].

For using gerrit review command line, it is recommended that you configure your ssh config file located in ~/.ssh/config and you add there our gerrit server:
 Host review
   Hostname osm.etsi.org
   Port 29418
   User youreolaccount

Then, to do a code review of a specific change, you can follow the instructions in [https://review.openstack.org/Documentation/cmd-review.html this link]. Some examples of the gerrit review command line below:
 ssh review gerrit review --verified +1 ce7f5a0b
 ssh review gerrit review --code-review +1 -m "'Looks good to me.'" ce7f5a0b
 ssh review gerrit review --verified +1 --code-review +2 --submit --project osm/RO ce7f5a0b
 ssh review gerrit review --label mylabel=+1 ce7f5a0b
 ssh review gerrit review --abandon ce7f5a0b

You can also do other things with gerrit command line, such as querying the open changes:
 ssh review gerrit query status:open project:osm/RO
 ssh review gerrit query status:open project:osm/RO limit:5