Staying close to latest from OpenStack through git-upstream
Go to file
Darragh Bailey bbf251148c Update ChangeLog for 0.12.1
Change-Id: I2fa848e6f80fa6b0062e5fe400750f796c899034
2016-11-02 15:38:24 +00:00
bash_completion Rename bash completion script 2014-03-17 13:54:22 +00:00
contrib/jjb Update typos 2015-12-30 10:50:43 +05:30
doc Include files for sphinx based documentation 2016-11-01 19:06:52 +00:00
functional-tests Update typos 2015-12-30 10:50:43 +05:30
git_upstream Ensure correct prog name available to manpage 2016-11-01 13:03:02 +00:00
.gitchangelog.rc Update ChangeLog with missing releases 2015-11-18 17:13:40 +00:00
.gitignore Update .gitignore with .eggs path for setuptools 2016-09-16 14:56:03 +01:00
.gitreview Update .gitreview for new namespace 2015-10-17 22:29:16 +00:00
.mailmap Have pbr update AUTHORS but not changelog 2016-01-15 17:22:43 +00:00
.testr.conf Move tests under module 2014-07-15 12:22:20 +01:00
ACKNOWLEDGEMENTS Add acknowledges file 2014-07-15 13:12:21 +01:00
AUTHORS Update authors 2016-11-01 13:03:02 +00:00
ChangeLog Update ChangeLog for 0.12.1 2016-11-02 15:38:24 +00:00
DESCRIPTION Change repository from stackforge to openstack 2015-10-18 22:32:14 +05:30
LICENSE Rename hpgit to git-upstream, also changing its license 2014-03-03 14:32:26 +00:00
README.md Update typos 2015-12-30 10:50:43 +05:30
USAGE.md Example in USAGE.md should reference .gitreview 2016-09-02 18:16:47 -04:00
docs-requirements.txt Include files for sphinx based documentation 2016-11-01 19:06:52 +00:00
requirements.txt Use a recent pbr 2016-08-31 11:50:29 +01:00
setup.cfg Include files for sphinx based documentation 2016-11-01 19:06:52 +00:00
setup.py Move build_manpage utility to doc area 2016-11-01 13:03:03 +00:00
test-requirements.txt Remove requirement sphinxcontrib-programoutput 2016-11-01 12:46:31 +00:00
tox.ini Include files for sphinx based documentation 2016-11-01 19:06:52 +00:00

README.md

What is git-upstream?

git-upstream is an open source Python application that can be used to keep in sync with upstream open source projects, mainly OpenStack.

The main usecase for this tool is for people who are doing active contributions to repositories that are mirrors of OpenStack repositories, with the intention that most of those contributions will be submitted to review.openstack.org at some point. If you are running a public cloud based on OpenStack, having local changes needed to use it in your environment, you can use git-upstream to stay up to date with the upstream master in a easier way (with respect to using raw git commands).

git-upstream provides new git subcommands to support rebasing of local-carried patches on top of upstream repositories. It provides commands to ease the use of git for who needs to integrate big upstream projects in their environment. The operations are performed using Git commands.

Note: currently git-upstream can be used only for projects that are maintained with Gerrit as it relies on the presence of Change-IDs. Nevertheless, the code is quite modular and can be extended to use any part of commit message (e.g., other headers).

Specifically, current git-upstream version supports the following features

  • Single upstream branch import

    Your repository is tracking an upstream project and has local changes applied and no other branch is merged in. This can also be applied to tracking upstream packaging branches: e.g., ubuntu/master => ubuntu/saucy-proposed/nova + local packaging changes.

  • Multi branch import (upstream branch + additional branches)

    In this case, your project tracks an upstream repository, merges in an arbitrary number of branches and applies local carried changes.

  • Re-reviewing

    Reviewing (w/ Gerrit) of all locally applied changes if desired. git-upstream creates an import branch in a manner that allows it to be fully re-reviewed or merged into master and pushed.

  • Detailed logging

    git-upstream can output to both console and log file simultaneously. Multiple levels and these are managed separately for log file and console output. This means jobs run by Jenkins can save a detailed log file separately as an artefact while printing status information to the console if those running the jobs dont wish to have the console spammed with the details.

  • Dropping of changes that appear upstream

    Compares Change-Id's of changes applied since previous import with those that have appeared on the upstream branch since the last import point.

  • Interactive mode

    Once the list of changes to be re-applied has been determined (and those to be dropped have been pruned), the tool can open an editor (controlled by your git editor settings) for users to review those changes to be made and allow them to perform further operations such as re-ordering, dropping of obsolete changes, squashing.

  • Dropping local changes

    Its always possible for local changes to be superseded by upstream changes, so when these are identified and marked as such, we should drop them.

    This can also occur where a change was applied locally, modified when being upstreamed based on review feedback and the resulting differences were ported to the internal as well. While the original change will be automatically dropped, also useful to drop the additional ported changes automatically if possible, rather than have it cause conflicts.

What git-upstream is not

The name of this tool includes the "git-" prefix because of the Git naming convention that a Git subcommand must have. So, as git-review (usually invoked with "git review [...]"), this tool can be invoked using "git upstream [...]".

That said, and even if git-upstream currently uses Change-Ids, it is not strictly related to git-review. In other words, git-review can (and most of the time will) be used without even knowing about git-upstream existence.

git-upstream installation

At the time of writing, there are two ways to install git-upstream: cloning its git repository or using pip.

Installing from git repository

git clone https://git.openstack.org/openstack/git-upstream.git
cd git-upstream
# Install git-upstream itself
python setup.py install

Installing from PyPI

pip install git-upstream

See also https://pypi.python.org/pypi/git-upstream

Using git-upstream

Please see USAGE.md

Available commands

import

Description

Import code from specified upstream branch. Creates an import branch from the specified upstream branch, and optionally merges additional branches given as arguments. Current branch, unless overridden by the --into option, is used as the target branch from which a list of changes to apply onto the new import is constructed based on the specified strategy. Once complete it will merge and replace the contents of the target branch with those from the import branch, unless --no-merge is specified.

Usage

git upstream import [-h] [-d] [-i] [-f] [--merge] [--no-merge]
                           [-s <strategy>] [--into <branch>]
                           [--import-branch <import-branch>]
                           [<upstream-branch>] [<branches> [<branches> ...]]

Arguments

positional arguments:
  <upstream-branch>     Upstream branch to import. Must be specified if you
                        wish to provide additional branches.
  <branches>            Branches to additionally merge into the import branch
                        using default git merging behaviour

optional arguments:
  -h, --help            show this help message and exit
  -d, --dry-run         Only print out the list of commits that would be
                        applied.
  -i, --interactive     Let the user edit the list of commits before applying.
  -f, --force           Force overwrite of existing import branch if it
                        exists.
  --merge               Merge the resulting import branch into the target
                        branch once complete
  --no-merge            Disable merge of the resulting import branch
  -s <strategy>, --strategy <strategy>
                        Use the given strategy to re-apply locally carried
                        changes to the import branch. (default: drop)
  --into <branch>       Branch to take changes from, and replace with imported
                        branch.
  --import-branch <import-branch>
                        Name of import branch to use

drop

Description

Mark a commit as dropped. Marked commits will be skipped during the upstream rebasing process.

See also the "git upstream import" command.

Usage

git upstream drop [-h] [-a <author>] <commit>

Arguments

positional arguments:
  <commit>              Commit to be marked as dropped

optional arguments:
  -h, --help            show this help message and exit
  -a <author>, --author <author>
                        Git author for the mark

Note

Commits will be marked with git notes in the namespace refs/notes/upstream-merge.

To list of commit id marked with a note, run git notes --ref refs/notes/upstream-merge.

To show a specific note run git notes --ref refs/notes/upstream-merge show <marked commit sha1>

As drop uses git notes to mark commits that have to be skipped during import, notes should be present on the cloned copy of your repository. Thus, if you are going to create notes on a system and perform the actual import on a different system, notes must be present on the latter.

You can push notes directly to git repository on the target system or push them in a different repository and then pull notes from your target system.

supersede

Description

Mark a commit as superseded by a set of change-ids. Marked commits will be skipped during the upstream rebasing process only if all the specified change-ids are present in <upstream-branch> during import. If you want to unconditionally drop a commit, use the drop command instead.

See also the "git upstream import" command.

Usage

git upstream supersede [-h] [-f] [-u <upstream-branch>]
                       <commit> <change id> [<change id> ...]

Arguments

positional arguments:
  <commit>              Commit to be marked as superseded
  <change id>           Change id which makes <commit> obsolete. The change id
                        must be present in <upstream-branch> to drop <commit>.
                        If more than one change id is specified, all must be
                        present in <upstream-branch> to drop <commit>

optional arguments:
  -h, --help            show this help message and exit
  -f, --force           Apply the commit mark even if one or more change ids
                        could not be found. Use this flag carefully as commits
                        will not be dropped during import command execution as
                        long as all associated change ids are present in the
                        local copy of the upstream branch
  -u <upstream-branch>, --upstream-branch <upstream-branch>
                        Search change ids values in <upstream-branch> branch
                        (default: upstream/master)

Note

This command doesn't perform the actual drop. Commits to be dropped during the next import, will be marked with git notes in the namespace refs/notes/upstream-merge. There is no need to retain notes after an import dropped the correspondent commits, of course it doesn't harm keeping them either.

To list of commit id marked with a note, run git notes --ref refs/notes/upstream-merge.

To show a specific note run git notes --ref refs/notes/upstream-merge show <marked commit sha1>.

As supersede uses git notes to mark commits that have to be skipped during import, notes should be present on the cloned copy of your repository. Thus, if you are going to create notes on a system and perform the actual import on a different system, notes must be present on the latter. You can push notes directly to git repository on the target system or push them in a different repository and then pull notes from your target system.

Authors

git-upstream was written by Darragh Bailey dbailey@hp.com.

Acknowledgements

Thanks to Aleksander Korzynski and Stanisław Pitucha for taking the original design spec and some basic manual steps and experimenting with initial implementations.

To Davide Guerri, for picking up a rough python tool and turning it into something that was actually usable.

Also to Jon Paul Sullivan and Monty Taylor to listening and providing a sounding board for different approaches.

And finally to Coleman Corrigan among numerous others who acted as willing guinea pigs for the original manual approach.

Hope this eventually helped save you time and some hair.