8.8 KiB
Tutorial: Developing Changes In A Series
This tutorial walks through a simple scenario of developing multiple change sets in a series on the same branch. If you wish, you can follow along, using the sandbox repository, executing the commands exactly as they're laid out.
If you are a visual learner, you may prefer this
video which does roughly the same thing (but without
git-restack
).
Here we go.
Start on a freshly-pull
ed master branch:
efried:~/openstack/sandbox$ git checkout master
Switched to branch 'master'
Your branch is up-to-date with 'origin/master'.
efried:~/openstack/sandbox$ git pull --all
<snip>
When you're working on a blueprint, you want to name your local
branch after the blueprint. For this example, we'll use
bp/nova-cyborg-interaction
.
efried:~/openstack/sandbox$ git checkout -b bp/nova-cyborg-interaction
Switched to a new branch 'bp/nova-cyborg-interaction'
efried:~/openstack/sandbox$ git log --oneline -1 --decorate
3d008a3 (HEAD -> bp/nova-cyborg-interaction, origin/master, origin/HEAD, gerrit/master, master) Merge "suggest change punctuation to english punctuantion"
When you git commit
(without --amend
),
you're creating a new commit on top of whatever commit you started at.
If you started with a clean, freshly pull
ed master branch,
that'll be whatever the most recently merged commit in the master branch
was. In this example, that's commit 3d008a3
.
So let's say I make an edit for my first patch and commit it:
efried:~/openstack/sandbox$ echo 'python-cyborgclient>=1.0' >> requirements.txt
efried:~/openstack/sandbox$ echo 'python-cyborgclient==1.1' >> lower-constraints.txt
efried:~/openstack/sandbox$ git add -A
efried:~/openstack/sandbox$ git commit -m "Add cyborg client to requirements"
[bp/nova-cyborg-interaction d76195e] Add cyborg client to requirements
2 files changed, 2 insertions(+)
create mode 100644 lower-constraints.txt
efried:~/openstack/sandbox$ git log --oneline -2 --decorate
d76195e (HEAD -> bp/nova-cyborg-interaction) Add cyborg client to requirements
3d008a3 (origin/master, origin/HEAD, gerrit/master, master) Merge "suggest change punctuation to english punctuantion"
I just made commit d76195e
on top of
3d008a3
. You'll notice my branch name
(bp/nova-cyborg-interaction
) came along with me.
Now I'm going to make another change, but just part of it, a work-in-progress commit:
efried:~/openstack/sandbox$ mkdir -p nova/pci/cyborg
efried:~/openstack/sandbox$ touch nova/pci/cyborg/__init__.py
efried:~/openstack/sandbox$ git add nova/pci/cyborg/__init__.py
efried:~/openstack/sandbox$ git commit -m "WIP: Cyborg PCI handling"
[bp/nova-cyborg-interaction f17f040] WIP: Cyborg PCI handling
1 file changed, 0 insertions(+), 0 deletions(-)
create mode 100644 nova/pci/cyborg/__init__.py
efried:~/openstack/sandbox$ git log --oneline -3 --decorate
f17f040 (HEAD -> bp/nova-cyborg-interaction) WIP: Cyborg PCI handling
d76195e Add cyborg client to requirements
3d008a3 (origin/master, origin/HEAD, gerrit/master, master) Merge "suggest change punctuation to english punctuantion"
Now commit f17f040
is on top of d76195e
,
which is still on top of 3d008a3
(aka master
).
Note that my branch name came with me again.
At this point, I push my series up to gerrit. Note that it makes me confirm that I really want to push two commits at once.
efried:~/openstack/sandbox$ git review
You are about to submit multiple commits. This is expected if you are
submitting a commit that is dependent on one or more in-review
commits, or if you are submitting multiple self-contained but
dependent changes. Otherwise you should consider squashing your
changes into one commit before submitting (for indivisible changes) or
submitting from separate branches (for independent changes).
The outstanding commits are:
f17f040 (HEAD -> bp/nova-cyborg-interaction) WIP: Cyborg PCI handling
d76195e Add cyborg client to requirements
Do you really want to submit the above commits?
Type 'yes' to confirm, other to cancel: yes
remote:
remote: Processing changes: new: 2, refs: 2
remote: Processing changes: new: 2, refs: 2
remote: Processing changes: new: 2, refs: 2, done
remote:
remote: New Changes:
remote: https://review.openstack.org/635341 Add cyborg client to requirements
remote: https://review.openstack.org/635342 WIP: Cyborg PCI handling
remote:
To ssh://review.openstack.org:29418/openstack-dev/sandbox.git
* [new branch] HEAD -> refs/for/master%topic=bp/nova-cyborg-interaction
Now if you go to either of those links - e.g. https://review.openstack.org/#/c/635342/ - you'll see that the patches are stacked up in series on the top right.
But oops, I made a mistake in my first commit. My lower constraint
can't be higher than my minimum in requirements.txt
. If I
still had my branch locally, I could skip this next step, but as a
matter of rigor to avoid some common pratfalls, I will pull the whole
series afresh from gerrit by asking git-review
to grab the
top change:
efried:~/openstack/sandbox$ git review -d 635342
Downloading refs/changes/42/635342/1 from gerrit
Switched to branch "review/eric_fried/bp/nova-cyborg-interaction"
Now I'm sitting on the top change (which you'll notice happens to be exactly the same as before I pushed it - again, meaning I could technically have just worked from where I was, but see above):
efried:~/openstack/sandbox$ git log --oneline -3 --decorate
f17f040 (HEAD -> review/eric_fried/bp/nova-cyborg-interaction, bp/nova-cyborg-interaction) WIP: Cyborg PCI handling
d76195e Add cyborg client to requirements
3d008a3 (origin/master, origin/HEAD, gerrit/master, master) Merge "suggest change punctuation to english punctuantion"
But I want to edit d76195e
, while leaving
f17f040
properly stacked on top of it. Here I use a tool
called git-restack
(run pip install git-restack
to install it).
efried:~/openstack/sandbox$ git restack
This pops me into an editor showing me all the commits between wherever I am and the main branch (now they're in top-first order):
pick d76195e Add cyborg client to requirements
pick f17f040 WIP: Cyborg PCI handling
<snip>
I want to fix the first one, so I change pick
to
edit
:
edit d76195e Add cyborg client to requirements
pick f17f040 WIP: Cyborg PCI handling
<snip>
Save and quit the editor, and I see:
Stopped at d76195e... Add cyborg client to requirements
You can amend the commit now, with
git commit --amend
Once you are satisfied with your changes, run
git rebase --continue
I fix lower-constraints.txt
:
efried:~/openstack/sandbox$ sed -i 's/cyborgclient==1.1/cyborgclient==1.0/' lower-constraints.txt
...and amend the current commit
efried:~/openstack/sandbox$ git commit -a --amend --no-edit
[detached HEAD df226f7] Add cyborg client to requirements
Date: Wed Feb 6 16:15:30 2019 -0600
2 files changed, 2 insertions(+)
create mode 100644 lower-constraints.txt
...and tell git-restack
to proceed
efried:~/openstack/sandbox$ git rebase --continue
Successfully rebased and updated refs/heads/review/eric_fried/bp/nova-cyborg-interaction.
If I had a taller series, and I had changed pick
to
edit
for more than one commit, I would now be sitting on
the next one I needed to edit. As it is, that was the only thing I
needed to do, so I'm done and sitting on the top of my series again.
efried:~/openstack/sandbox$ git log --oneline -3 --decorate
e937eef (HEAD -> review/eric_fried/bp/nova-cyborg-interaction) WIP: Cyborg PCI handling
df226f7 Add cyborg client to requirements
3d008a3 (origin/master, origin/HEAD, gerrit/master, master) Merge "suggest change punctuation to english punctuantion"
Notice that the commit hashes have changed for both commits
(but not for master
). The top one changed because it got
rebased onto the new version of the middle one.
Now if I push the series back up to gerrit, I get the same confirmation prompt, and both changes get a new patch set. If you look at the top patch in gerrit, you'll see that patch set 2 shows up as just a rebase.