# 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 [here](05-git-review.md). Optionally, you can use git, as described in this [link](04-merge-conflicts.md).

## Install and configure `git-review`

```bash
$ sudo apt-get install git-review
```

Optionally, you could install it through pip:

```bash
$ 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:

```bash
$ 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:

```bash
$ 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:

```bash
$ 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.

```bash
$ git review -s
```

## Push your changes to gerrit

First, commit your files locally:

```bash
$ 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
```

Then push your commits to gerrit, with `git review -c`.

```bash
$ 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
```

**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`

```bash
$ 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

```bash
$ 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 branches in gerrit.

### Listing open reviews

```bash
git review -l
```

### Submitting for review

- To add a topic:

```bash
git review -t topic/blahblahblah
```

- To add reviewers

```bash
git review --reviewers john@aaa.com tracy@bbb.com
```

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

```bash
git review -f
```

- To submit for review as a draft:

```bash
git review -D
```

### Reviewing

- To download a change using change number:

```bash
git review -d 1200
```

- To download a specific patchset:

```bash
git review -d 1200,2
```

- To compare two patches of the same change:

```bash
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 [gerrit command line](https://review.openstack.org/Documentation/cmd-index.html).

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:

```text
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 [this link](https://review.openstack.org/Documentation/cmd-review.html). Some examples of the gerrit review command line below:

```bash
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:

```bash
ssh review gerrit query status:open project:osm/RO
ssh review gerrit query status:open project:osm/RO limit:5
```