diff --git a/README.md b/README.md deleted file mode 100644 index 7335e1d..0000000 --- a/README.md +++ /dev/null @@ -1,289 +0,0 @@ -# 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 don’t 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** - - It’s 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 - -```bash -git clone https://git.openstack.org/openstack/git-upstream.git -cd git-upstream -# Install git-upstream itself -python setup.py install -``` - -## Installing from PyPI - -```bash -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 ] [--into ] - [--import-branch ] - [] [ [ ...]] -``` - -### Arguments - -``` -positional arguments: - Upstream branch to import. Must be specified if you - wish to provide additional 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 - Use the given strategy to re-apply locally carried - changes to the import branch. (default: drop) - --into Branch to take changes from, and replace with imported - 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 ] -``` - -### Arguments - -``` -positional arguments: - Commit to be marked as dropped - -optional arguments: - -h, --help show this help message and exit - -a , --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 -` - - -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 `` 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 ] - [ ...] -``` - -### Arguments - -``` -positional arguments: - Commit to be marked as superseded - Change id which makes obsolete. The change id - must be present in to drop . - If more than one change id is specified, all must be - present in to drop - -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 - Search change ids values in 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 -`. - - -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 . - -# 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. diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..3258b9b --- /dev/null +++ b/README.rst @@ -0,0 +1,324 @@ +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). + + +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 don’t 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** + +It’s 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 +------------------------------ + +.. code:: bash + + git clone https://git.openstack.org/openstack/git-upstream.git + cd git-upstream + # Install git-upstream itself + python setup.py install + +Installing from PyPI +-------------------- + +.. code:: bash + + 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 ] [--into ] + [--import-branch ] + [] [ [ ...]] + +Arguments +~~~~~~~~~ + +:: + + positional arguments: + Upstream branch to import. Must be specified if you + wish to provide additional 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 + Use the given strategy to re-apply locally carried + changes to the import branch. (default: drop) + --into Branch to take changes from, and replace with imported + 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 ] + +Arguments +~~~~~~~~~ + +:: + + positional arguments: + Commit to be marked as dropped + + optional arguments: + -h, --help show this help message and exit + -a , --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 `` + +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 ```` 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 ] + [ ...] + +Arguments +~~~~~~~~~ + +:: + + positional arguments: + Commit to be marked as superseded + Change id which makes obsolete. The change id + must be present in to drop . + If more than one change id is specified, all must be + present in to drop + + 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 + Search change ids values in 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 ``. + +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@hpe.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.