Jump to: navigation, search

Git-review Workflow

(Redirected from GettingStarted:PushAndFix)

Gerrit Workflow

git-review is a command-line tool for Git / Gerrit. It makes it easier to configure your git clone, to submit a change or to fetch an existing one.

The upstream project is led by OpenStack. Not to be confused with the unrelated Facebook project.

Initial Setup

Clone your git repository, and in the root directory enter the following

git-review -s
git config user.name "Firstname Lastname"
git config user.email your_email@some.domain

This will set up your connection to Gerrit as well as your commit author and email. You can also pass the "--global" option if you want this to apply system wide rather then to the repo. For example:

git config --global user.name Firstname Lastname
git config --global user.email your_email@some.domain

Submitting Patches

The typical workflow when working on a new patch in Gerrit is to start off with a new branch representing the new feature or bug being fixed. This branch should only ever have exactly 1 commit off of origin/master and continuously "git commit --amend" to update the patch. A typical workflow might look like this:

git fetch origin
git checkout -b new_feature origin/master
git add <files>
git commit -s
gitk
  • We fetch origin to pull down the latest version of the code base to ensure that when branch with the most up to date code
  • The git checkout -b command creates a new branch called new_feature (you should name this appropriately)
  • Git add files you've modified to the staging area
  • Finally git commit with a relevant commit message the "-s" command signs off your commit message which is required to submit code to ODL.
  • Commit messages should be written in present-tense, imperative-style see examples of commit messages here https://wiki.openstack.org/wiki/GitCommitMessages
  • Use gitk to verify your changes are as you expect, it is good practice to check this often.

Note: To be accepted, all code must come with a developer certificate of origin as expressed by having a Signed-off-by. This means that you are asserting that you have made the change and you understand that the work was done as part of an open-source license.

Developer's Certificate of Origin 1.1

        By making a contribution to this project, I certify that:

        (a) The contribution was created in whole or in part by me and I
            have the right to submit it under the open source license
            indicated in the file; or

        (b) The contribution is based upon previous work that, to the best
            of my knowledge, is covered under an appropriate open source
            license and I have the right under that license to submit that
            work with modifications, whether created in whole or in part
            by me, under the same open source license (unless I am
            permitted to submit under a different license), as indicated
            in the file; or

        (c) The contribution was provided directly to me by some other
            person who certified (a), (b) or (c) and I have not modified
            it.

        (d) I understand and agree that this project and the contribution
            are public and that a record of the contribution (including all
            personal information I submit with it, including my sign-off) is
            maintained indefinitely and may be redistributed consistent with
            this project or the open source license(s) involved.

Mechanically you do it this way (long and short form):

git commit --signoff
git commit -s

If you wish to add the signoff to the commit message on your every commit without the need to specify -s or --signoff, add the following lines in the end of .git/hooks/commit-msg, after the line "add_ChangeId":

SOB=$(git var GIT_AUTHOR_IDENT | sed -n 's/^\(.*>\).*$/Signed-off-by: \1/p')
grep -qs "^$SOB" "$1" || echo "$SOB" >> "$1"

Once you've added and committed your changes, you can use git-review to publish to Gerrit after confirming your changes are up to date with upstream.

git fetch origin
git rebase origin/master
gitk
git review

The pattern git fetch, rebase, and gitk should be used often when you start working on a new change as well as just before you push your changes online, resolve any merge conflicts. If your branch is up to date you should be exactly 1 commit away from origin/master in the gitk graph view.

Git-review will rebase your changes against the master branch in Gerrit before pushing. It will also notify you of merge conflicts so you can manually resolve them. You can disable the rebase by using the -R or --no-rebase flags.

Adding a Bug

The last block of a commit message where your signed-off-by line is, is used by git as metadata fields. If you are working on something related to a bug you should add "Bug: 1234" to the commit message just above the Change-Id or Signed-off-by fields, it should be in the same block (no blank lines between them). If you forgot to do this when you committed you can amend your commit to add the metadata.

git commit --amend
# Add Bug: 1234 just above the Change-Id or Signed-off-by field

Adding a topic

By default, the Gerrit topic will be the name of your local branch. You can change this using the -t or --topic flags.

git review -t topic

Pushing to a feature branch

To push to a branch other than master, just add the branch name.

git review topic/schema
git review stable/hydrogen

Pushing a draft

Pushing to drafts is easy:

git review -D

or

git review --draft

Adding a dependency

To make your commit dependent upon another (parent) change...

# 
git review -d 6150
# Create a new branch called foo
git checkout -b foo
git commit 
git review -R

The -R option is there to avoid rebasing the parent change, as that would interfere with parent author view. Of course rebasing is encouraged if parent is already merged.

Updating a Patch (created from git remote brach)

Assuming you already have the local branch with your patch in, simply make your changes...

git commit --amend
git fetch origin
git rebase origin/master
gitk  # Verify your changes
git review

You should always follow the pattern fetch, rebase, and gitk to pull down the most recent code and rebase your code ontop of it and finally gitk verify your changes are as you expect.

Alternatively you can checkout a patch to review use the -d flag followed by the change number in Gerrit

git review -d 6150

Make your changes and resubmit to Gerrit.

git commit --amend
git review -t <original-topic> -f

-f will delete the local branch and checkout the master branch.

Getting Latest Dependent Change ("Rebase" without running rebase command)

In case the dependent change (parent-change) set was updated and you wish to "rebase" your change (child-change).

Fetch and checkout the parent change:

git review -d <parent-gerrit-id>

Cherry-pick your commit on top of it:

git review -x <child-gerrit-id>

Submit "rebased" change for review:

git review -R

Reviewing Patches

If you are downloading code to make changes or test functionality you can do so as follows:

git review -d 6150
git commit --amend
git review -t <original-topic> -f

If you wish to diff between two patch sets you can do so using git-review

git review -m 6150,3

Will diff between Patch Set 3 of change 6150 and the latest Patch Set.

Further Reading

The git-review wiki page is a great resource.

Appendix A: Why Gerrit Topics are Awesome!

Topics can be used as a search criteria in Gerrit by typing topic:foo. This allows commits that are part of a feature to be easily tracked.