Wrap markdown documentation to 80 characters
The markdown files where not wrapped at 80 characters making it difficult to read in plain text and not conforming the normal documentation standards on OpenStack. Change-Id: I028a721866e4a62ee87730a5d3d8050c913f2867
This commit is contained in:
parent
8ff1af4bd9
commit
9ad1992036
|
@ -2,9 +2,18 @@
|
|||
|
||||
## Problem description
|
||||
|
||||
If previous local changes were based off of a point before the previous import merge was complete, and were not rebased to be applied after this point before being merged, the import command will miss including these when discarding previous obsolete history.
|
||||
If previous local changes were based off of a point before the previous import
|
||||
merge was complete, and were not rebased to be applied after this point before
|
||||
being merged, the import command will miss including these when discarding
|
||||
previous obsolete history.
|
||||
|
||||
Given a previous import like the following where previously changes B & C were replayed, and the import was merged as E. Where subsequently a change D which was proposed before the import, is merged to mainline, a subsequent run of the tool to import K will fail to include D along with B', C' & G' when discarding the assumed unnecessary merges E & F. While these should be discarded, the tool needs to check to make sure if there are dangling changes that should be included.
|
||||
Given a previous import like the following where previously changes B & C were
|
||||
replayed, and the import was merged as E. Where subsequently a change D which
|
||||
was proposed before the import, is merged to mainline, a subsequent run of the
|
||||
tool to import K will fail to include D along with B', C' & G' when discarding
|
||||
the assumed unnecessary merges E & F. While these should be discarded, the tool
|
||||
needs to check to make sure if there are dangling changes that should be
|
||||
included.
|
||||
|
||||
D----
|
||||
/ \
|
||||
|
@ -26,7 +35,8 @@ The tool will find the following commit path to consider:
|
|||
|
||||
## Implementing a fix (WiP)
|
||||
|
||||
With respect to the previous diagrams, the correct behaviour is to find the following set:
|
||||
With respect to the previous diagrams, the correct behaviour is to find the
|
||||
following set:
|
||||
|
||||
D----
|
||||
\
|
||||
|
@ -36,13 +46,21 @@ With respect to the previous diagrams, the correct behaviour is to find the foll
|
|||
/
|
||||
G
|
||||
|
||||
This requires walking the list of initial found (2nd diagram) and examining each merge commit up to the previous import to see if there is a change that shares history with the other parent. i.e. look at F and see if D contains a merge-base in common with E, an thus include. Or locate E and find any differences between E & L that should be included.
|
||||
This requires walking the list of initial found (2nd diagram) and examining
|
||||
each merge commit up to the previous import to see if there is a change that
|
||||
shares history with the other parent. i.e. look at F and see if D contains a
|
||||
merge-base in common with E, an thus include. Or locate E and find any
|
||||
differences between E & L that should be included.
|
||||
|
||||
## Workaround
|
||||
|
||||
Waiting for a proper fix to be implemented, a workaround for this issue would be to perform the import only into a branch (usually master) which has no "pending" commits in other branches to be merged that span across different imports.
|
||||
Waiting for a proper fix to be implemented, a workaround for this issue would
|
||||
be to perform the import only into a branch (usually master) which has no
|
||||
"pending" commits in other branches to be merged that span across different
|
||||
imports.
|
||||
|
||||
For gerrit this means not having pending reviews spanning across different git-upstream import command runs.
|
||||
For gerrit this means not having pending reviews spanning across different
|
||||
git-upstream import command runs.
|
||||
|
||||
This could be achieved in two different ways:
|
||||
1) merging all pending reviews before an import;
|
||||
|
|
147
README.md
147
README.md
|
@ -1,59 +1,92 @@
|
|||
# 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.
|
||||
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).
|
||||
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.
|
||||
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).
|
||||
**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.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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 [...]".
|
||||
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.
|
||||
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.
|
||||
At the time of writing, there are two ways to install git-upstream: cloning its
|
||||
git repository or using pip.
|
||||
|
||||
## Installing from git repository
|
||||
|
||||
|
@ -81,7 +114,13 @@ Please see `USAGE.md`
|
|||
|
||||
### 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 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.
|
||||
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 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
|
||||
|
||||
|
@ -124,7 +163,8 @@ optional arguments:
|
|||
|
||||
### Description
|
||||
|
||||
Mark a commit as dropped. Marked commits will be skipped during the upstream rebasing process.
|
||||
Mark a commit as dropped. Marked commits will be skipped during the upstream
|
||||
rebasing process.
|
||||
|
||||
See also the "git upstream import" command.
|
||||
|
||||
|
@ -148,20 +188,32 @@ optional arguments:
|
|||
|
||||
### 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>`
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
|
||||
|
@ -196,15 +248,25 @@ optional arguments:
|
|||
|
||||
### 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.
|
||||
*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>`.
|
||||
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.
|
||||
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.
|
||||
|
||||
# Known issues
|
||||
|
||||
|
@ -215,12 +277,17 @@ 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.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
|
|
134
USAGE.md
134
USAGE.md
|
@ -1,8 +1,12 @@
|
|||
# Importing from upstream: using git-upstream
|
||||
|
||||
**Note**: this guide assumes that you are using a branch named *master* to maintain your new features or bug fixes that sit on top of the upstream code of some project (probably somewhat related to OpenStack).
|
||||
**Note**: this guide assumes that you are using a branch named *master* to
|
||||
maintain your new features or bug fixes that sit on top of the upstream code of
|
||||
some project (probably somewhat related to OpenStack).
|
||||
|
||||
It is also assumed you are tracking releases, which is only one of the possible approaches to upstream tracking. Another approach would be tracking the master tip of a project. Of course even other strategies are possible.
|
||||
It is also assumed you are tracking releases, which is only one of the possible
|
||||
approaches to upstream tracking. Another approach would be tracking the master
|
||||
tip of a project. Of course even other strategies are possible.
|
||||
|
||||
## Install git-upstream on a development workstation
|
||||
|
||||
|
@ -49,9 +53,11 @@ usage: git-upstream [--version] [-h] [-q | -v] <command> ...
|
|||
|
||||
## Initial import of an upstream project
|
||||
|
||||
To explain the usage of the git-upstream tool We are going to use a real-world (but trivial) example.
|
||||
To explain the usage of the git-upstream tool We are going to use a real-world
|
||||
(but trivial) example.
|
||||
|
||||
We will be also using environment variables: in case you are keen on doing copy-paste, you will only need to change them to suite your environment.
|
||||
We will be also using environment variables: in case you are keen on doing
|
||||
copy-paste, you will only need to change them to suite your environment.
|
||||
|
||||
```bash
|
||||
export REPO_NAME="jenkins-job-builder"
|
||||
|
@ -85,7 +91,9 @@ git fetch --all
|
|||
|
||||
4) Push refs
|
||||
|
||||
Push refs defined upstream to the `origin` remote (*i.e.*, the internal copy of the repository with local patches) using the string `upstream` as prefix, also pushing tags.
|
||||
Push refs defined upstream to the `origin` remote (*i.e.*, the internal copy
|
||||
of the repository with local patches) using the string `upstream` as prefix,
|
||||
also pushing tags.
|
||||
|
||||
```bash
|
||||
git for-each-ref refs/remotes/upstream --format "%(refname:short)" | \
|
||||
|
@ -93,7 +101,8 @@ git for-each-ref refs/remotes/upstream --format "%(refname:short)" | \
|
|||
xargs git push --tags origin
|
||||
```
|
||||
|
||||
You may want to repeat the last two commands before starting any new feature development or a bug fix.
|
||||
You may want to repeat the last two commands before starting any new feature
|
||||
development or a bug fix.
|
||||
|
||||
5) Check-out the first import commit (*e.g.*, tag or SHA1)
|
||||
|
||||
|
@ -109,9 +118,11 @@ git checkout -b import/$FIRST_IMPORT_REF $FIRST_IMPORT_REF
|
|||
git checkout -b master
|
||||
```
|
||||
|
||||
Now the tips of master, `$FIRST_IMPORT_REF` and `import/$FIRST_IMPORT_REF` should be pointing to the same commit.
|
||||
Now the tips of master, `$FIRST_IMPORT_REF` and `import/$FIRST_IMPORT_REF`
|
||||
should be pointing to the same commit.
|
||||
|
||||
Push local master branch to the remote origin, and make `origin master` the default when pushing commits.
|
||||
Push local master branch to the remote origin, and make `origin master` the
|
||||
default when pushing commits.
|
||||
|
||||
```bash
|
||||
git push -u origin master
|
||||
|
@ -120,7 +131,8 @@ git push -u origin master
|
|||
## Writing your patches/features
|
||||
|
||||
Now start to develop new feature or fix bugs on master, as usual.
|
||||
For this example, we are going to change the .gitreview file in order to use a local Gerrit server.
|
||||
For this example, we are going to change the .gitreview file in order to use a
|
||||
local Gerrit server.
|
||||
|
||||
echo "diff --git a/.gitreview b/.gitreview
|
||||
index bb7e85c..f98d928 100644
|
||||
|
@ -134,7 +146,8 @@ index bb7e85c..f98d928 100644
|
|||
-project=openstack-infra/jenkins-job-builder.git
|
||||
+project=my-projects/jenkins-job-builder.git" | patch -p1
|
||||
|
||||
Don’t forget to commit and push (after this step, you may want to use git review as usual)
|
||||
Don’t forget to commit and push (after this step, you may want to use git
|
||||
review as usual)
|
||||
|
||||
```bash
|
||||
git commit -a -m "Set .gitignore content to use internal gating infra"
|
||||
|
@ -145,12 +158,19 @@ Our master (local and remote) tip should be now pointing to the last commit.
|
|||
|
||||
## Importing single patches from upstream
|
||||
|
||||
Before implementing any feature or fixing any bug (in short, before reinventing the wheel), check if someone has already implemented the required code upstream.
|
||||
Before implementing any feature or fixing any bug (in short, before reinventing
|
||||
the wheel), check if someone has already implemented the required code
|
||||
upstream.
|
||||
|
||||
If not, try not to develop code only for your specific needs, be ambitious and try to develop something that could be useful for the whole community. This way you can propose your patch upstream and save yourself a lot of trouble which arise when there are many local changes to carry on the tip of upstream releases.
|
||||
If not, try not to develop code only for your specific needs, be ambitious and
|
||||
try to develop something that could be useful for the whole community. This way
|
||||
you can propose your patch upstream and save yourself a lot of trouble which
|
||||
arise when there are many local changes to carry on the tip of upstream
|
||||
releases.
|
||||
|
||||
In this example, we tried to use our code and we found out that the job filtering isn’t working!
|
||||
Fortunately, Antoine Musso has already fixed this bug, as we can see in the upstream repo.
|
||||
In this example, we tried to use our code and we found out that the job
|
||||
filtering isn’t working! Fortunately, Antoine Musso has already fixed this bug,
|
||||
as we can see in the upstream repo.
|
||||
|
||||
```bash
|
||||
git show --summary 2eca0d11669b55d4ab02ba609a15aa242fd80d14
|
||||
|
@ -175,7 +195,8 @@ Date: Mon Jun 24 14:36:52 2013 +0200
|
|||
Tested-by: Jenkins
|
||||
```
|
||||
|
||||
We are also interested in the following commit, which adds the Environment File Plugin (finally!).
|
||||
We are also interested in the following commit, which adds the Environment File
|
||||
Plugin (finally!).
|
||||
|
||||
```bash
|
||||
~# git show --summary bf4524fae25c11640ef839aa422ac81bd926ca20
|
||||
|
@ -197,7 +218,8 @@ Date: Mon Jul 1 11:21:24 2013 -0700
|
|||
Tested-by: Jenkins
|
||||
```
|
||||
|
||||
Import those changes simply cherry-picking the two commits. Don’t forget to push (review!) your changes.
|
||||
Import those changes simply cherry-picking the two commits. Don’t forget to
|
||||
push (review!) your changes.
|
||||
|
||||
```bash
|
||||
git cherry-pick 2eca0d11669b55d4ab02ba609a15aa242fd80d14
|
||||
|
@ -216,9 +238,13 @@ git for-each-ref refs/remotes/upstream --format "%(refname:short)" | \
|
|||
xargs git push --tags origin
|
||||
```
|
||||
|
||||
A lot of work has been done upstream and we need to rebase our master onto the upstream master branch. In this process we must skip all the commits we already cherry-picked some days ago, of course.
|
||||
A lot of work has been done upstream and we need to rebase our master onto the
|
||||
upstream master branch. In this process we must skip all the commits we already
|
||||
cherry-picked some days ago, of course.
|
||||
|
||||
**Note**: the rebasing for this example is trivial but it is just to break the ice. Later in this guide we will address rebasing conflicts that can occur in the real world.
|
||||
**Note**: the rebasing for this example is trivial but it is just to break the
|
||||
ice. Later in this guide we will address rebasing conflicts that can occur in
|
||||
the real world.
|
||||
|
||||
Create a new local branch with the new release tag as a starting point
|
||||
|
||||
|
@ -227,7 +253,8 @@ git branch import/0.6.0 0.6.0
|
|||
```
|
||||
## Running git-upstream
|
||||
|
||||
Finally, it is time to run git-upstream! Before doing so make sure the current branch is master
|
||||
Finally, it is time to run git-upstream! Before doing so make sure the current
|
||||
branch is master
|
||||
|
||||
```bash
|
||||
git checkout master
|
||||
|
@ -251,7 +278,10 @@ import branch: 'import/0.6.0'
|
|||
|
||||
What has just happened?
|
||||
|
||||
git-upstream has created a new branch named `import/0.6.0-base` which tip is set to the commit pointed by the release tag `0.6.0`, and has rebased all changes present in our local master which were not already present in the upstream new release (`import/0.6.0-base`) onto `import/0.6.0-base`.
|
||||
git-upstream has created a new branch named `import/0.6.0-base` which tip is
|
||||
set to the commit pointed by the release tag `0.6.0`, and has rebased all
|
||||
changes present in our local master which were not already present in the
|
||||
upstream new release (`import/0.6.0-base`) onto `import/0.6.0-base`.
|
||||
|
||||
You can see that running the following command
|
||||
|
||||
|
@ -259,10 +289,13 @@ You can see that running the following command
|
|||
git log --graph --oneline --all --decorate
|
||||
```
|
||||
|
||||
For this trivial example, the only commit not present in the upstream release was about the customisation of the .gitreview file.
|
||||
For this trivial example, the only commit not present in the upstream release
|
||||
was about the customisation of the .gitreview file.
|
||||
|
||||
The default strategy git-upstream uses to find duplicate entries is the comparison of Change-id entries in commit messages.
|
||||
Of course, it’s not possible to compare directly the SHA1 for a commit because the cherry-picking changes the information used for SHA1 calculation
|
||||
The default strategy git-upstream uses to find duplicate entries is the
|
||||
comparison of Change-id entries in commit messages. Of course, it’s not
|
||||
possible to compare directly the SHA1 for a commit because the cherry-picking
|
||||
changes the information used for SHA1 calculation
|
||||
|
||||
---
|
||||
**Note**: A git commit SHA1 is generated from the following information:
|
||||
|
@ -275,12 +308,23 @@ Of course, it’s not possible to compare directly the SHA1 for a commit because
|
|||
|
||||
---
|
||||
|
||||
The local branch `import/0.6.0` now contains our local changes rebased onto the new upstream release. git-upstream has also merged this branch with the local master branch (with "ours" strategy) to allow the normal workflow (committing/merging to master for review).
|
||||
The local branch `import/0.6.0` now contains our local changes rebased onto the
|
||||
new upstream release. git-upstream has also merged this branch with the local
|
||||
master branch (with "ours" strategy) to allow the normal workflow
|
||||
(committing/merging to master for review).
|
||||
|
||||
**Note**: The "final" merging step is not mandatory. Of course you can keep a separate branch for each new import. On one hand this strategy allows a "cleaner" history as you will always have your local changes rebased on top of the exact copy of the upstream repository. On the other hand you will be creating a new branch every time you want to import upstream code.
|
||||
You can customise the name of the import branch using the `--import-branch <branch name>` option.
|
||||
**Note**: The "final" merging step is not mandatory. Of course you can keep a
|
||||
separate branch for each new import. On one hand this strategy allows a
|
||||
"cleaner" history as you will always have your local changes rebased on top of
|
||||
the exact copy of the upstream repository. On the other hand you will be
|
||||
creating a new branch every time you want to import upstream code.
|
||||
You can customise the name of the import branch using the `--import-branch
|
||||
<branch name>` option.
|
||||
|
||||
In principle, you could also replace your master branch (history) with the new import branch created by git-upstream... Unfortunately there is no way to do this without requiring ad-hoc intervention on cloned copies of the repository (aka do-not-do-that(TM))
|
||||
In principle, you could also replace your master branch (history) with the new
|
||||
import branch created by git-upstream... Unfortunately there is no way to do
|
||||
this without requiring ad-hoc intervention on cloned copies of the repository
|
||||
(aka do-not-do-that(TM))
|
||||
|
||||
To disable automatic merging, just use the `--no-merge` flag
|
||||
|
||||
|
@ -290,9 +334,12 @@ To disable automatic merging, just use the `--no-merge` flag
|
|||
|
||||
# Handling conflicts
|
||||
|
||||
Of course n the real world things are much more complicated. From time to time, during import, you will get rebasing conflict (for instance due to changes from both local and upstream repository to the same piece of code).
|
||||
Of course n the real world things are much more complicated. From time to time,
|
||||
during import, you will get rebasing conflict (for instance due to changes from
|
||||
both local and upstream repository to the same piece of code).
|
||||
|
||||
In case of rebasing conflict, git-upstream will stop allowing the user to fix the conflict.
|
||||
In case of rebasing conflict, git-upstream will stop allowing the user to fix
|
||||
the conflict.
|
||||
|
||||
```bash
|
||||
~# git-upstream import import/0.5.0 --into master
|
||||
|
@ -309,7 +356,8 @@ Could not apply f9b4fca... Fixup for openstack review
|
|||
Import cancelled
|
||||
```
|
||||
|
||||
Let's find out why git-upstream failed and let's try to continue the rebasing manually.
|
||||
Let's find out why git-upstream failed and let's try to continue the rebasing
|
||||
manually.
|
||||
|
||||
```bash
|
||||
~# git status
|
||||
|
@ -337,10 +385,12 @@ Depending on the type of conflict, you will could:
|
|||
|
||||
* edit conflicting code
|
||||
|
||||
Change conflicting code in order to accomodate local changes to the new upstream code.
|
||||
Change conflicting code in order to accommodate local changes to the new
|
||||
upstream code.
|
||||
You can later resume rebasing process issuing `git rebase --continue`
|
||||
|
||||
Currently git-upstream can't resume the rebasing process. So, if needed, the final "merging" steps have to be performed manually:
|
||||
Currently git-upstream can't resume the rebasing process. So, if needed, the
|
||||
final "merging" steps have to be performed manually:
|
||||
|
||||
```bash
|
||||
git merge -s ours --no-commit <import-xxxx>
|
||||
|
@ -358,17 +408,20 @@ Committing merge commit
|
|||
git commit --no-edit
|
||||
```
|
||||
|
||||
**Note**: git-upstream performs exactly those steps in order to replace the content of `master` branch with the import branch preserving the history.
|
||||
**Note**: git-upstream performs exactly those steps in order to replace the
|
||||
content of `master` branch with the import branch preserving the history.
|
||||
|
||||
# Integration with Gerrit
|
||||
|
||||
You may want to use review with Gerrit the output of git-upstream, in order to perform tests, gating, etc.
|
||||
You may want to use review with Gerrit the output of git-upstream, in order to
|
||||
perform tests, gating, etc.
|
||||
|
||||
You have 2 options for doing that:
|
||||
|
||||
## Re-review every new commit
|
||||
|
||||
In this case we want to review every new commit (wrt the last import). In order to do so, use the `--no-merge` flag of git-upstream import commend, and:
|
||||
In this case we want to review every new commit (since the last import). In
|
||||
order to do so, use the `--no-merge` flag of git-upstream import command, and:
|
||||
|
||||
```bash
|
||||
git checkout import-xxxxx
|
||||
|
@ -376,11 +429,14 @@ git push gerrit import-xxxxx-base:import-xxxxx
|
|||
git review import-xxxxx
|
||||
```
|
||||
|
||||
If there is more than one new commit, git-review will ask to confirm the submission of multiple changes.
|
||||
If there is more than one new commit, git-review will ask to confirm the
|
||||
submission of multiple changes.
|
||||
|
||||
## Re-review only the final merge commit
|
||||
|
||||
This would be possible by using the `--import-branch` option of import command and **pushing directly** (*i.e.*: bypassing Gerrit) the new branch to the local repo. For instance:
|
||||
This would be possible by using the `--import-branch` option of import command
|
||||
and **pushing directly** (*i.e.*: bypassing Gerrit) the new branch to the local
|
||||
repo. For instance:
|
||||
|
||||
```bash
|
||||
TIMESTAMP=$(date +"%Y%m%d%H%M%s")
|
||||
|
@ -394,7 +450,9 @@ Then, create a valid `Change-Id` for the merge commit
|
|||
git commit --amend -C HEAD --no-edit
|
||||
```
|
||||
|
||||
Locally, git-review will still complain about the presence of N+M commits which would be committed BUT on the remote side all those commits will be recognised as already present in one of the two branch involved in the merge.
|
||||
Locally, git-review will still complain about the presence of N+M commits which
|
||||
would be committed BUT on the remote side all those commits will be recognised
|
||||
as already present in one of the two branch involved in the merge.
|
||||
|
||||
```bash
|
||||
git review -R -y master
|
||||
|
|
Loading…
Reference in New Issue