git-format-patch: the default suffix is now .patch, not .txt
[git/git.git] / Documentation / howto / rebase-from-internal-branch.txt
CommitLineData
365a00a3
RA
1From: Junio C Hamano <junkio@cox.net>
2To: git@vger.kernel.org
3Cc: Petr Baudis <pasky@suse.cz>, Linus Torvalds <torvalds@osdl.org>
4Subject: Re: sending changesets from the middle of a git tree
5Date: Sun, 14 Aug 2005 18:37:39 -0700
f358c10f
JH
6Abstract: In this article, JC talks about how he rebases the
7 public "pu" branch using the core GIT tools when he updates
8 the "master" branch, and how "rebase" works. Also discussed
9 is how this applies to individual developers who sends patches
10 upstream.
365a00a3
RA
11
12Petr Baudis <pasky@suse.cz> writes:
13
14> Dear diary, on Sun, Aug 14, 2005 at 09:57:13AM CEST, I got a letter
15> where Junio C Hamano <junkio@cox.net> told me that...
16>> Linus Torvalds <torvalds@osdl.org> writes:
17>>
18>> > Junio, maybe you want to talk about how you move patches from your "pu"
19>> > branch to the real branches.
20>>
21> Actually, wouldn't this be also precisely for what StGIT is intended to?
22
23Exactly my feeling. I was sort of waiting for Catalin to speak
24up. With its basing philosophical ancestry on quilt, this is
25the kind of task StGIT is designed to do.
26
27I just have done a simpler one, this time using only the core
28GIT tools.
29
30I had a handful commits that were ahead of master in pu, and I
31wanted to add some documentation bypassing my usual habit of
32placing new things in pu first. At the beginning, the commit
33ancestry graph looked like this:
34
35 *"pu" head
36 master --> #1 --> #2 --> #3
37
38So I started from master, made a bunch of edits, and committed:
39
40 $ git checkout master
e47e35ac 41 $ cd Documentation; ed git.txt ...
365a00a3 42 $ cd ..; git add Documentation/*.txt
22a06b3c 43 $ git commit -s
365a00a3
RA
44
45After the commit, the ancestry graph would look like this:
46
47 *"pu" head
48 master^ --> #1 --> #2 --> #3
49 \
50 \---> master
51
52The old master is now master^ (the first parent of the master).
53The new master commit holds my documentation updates.
54
55Now I have to deal with "pu" branch.
56
57This is the kind of situation I used to have all the time when
58Linus was the maintainer and I was a contributor, when you look
59at "master" branch being the "maintainer" branch, and "pu"
60branch being the "contributor" branch. Your work started at the
61tip of the "maintainer" branch some time ago, you made a lot of
62progress in the meantime, and now the maintainer branch has some
63other commits you do not have yet. And "git rebase" was written
64with the explicit purpose of helping to maintain branches like
65"pu". You _could_ merge master to pu and keep going, but if you
66eventually want to cherrypick and merge some but not necessarily
67all changes back to the master branch, it often makes later
68operations for _you_ easier if you rebase (i.e. carry forward
69your changes) "pu" rather than merge. So I ran "git rebase":
70
71 $ git checkout pu
72 $ git rebase master pu
73
74What this does is to pick all the commits since the current
75branch (note that I now am on "pu" branch) forked from the
76master branch, and forward port these changes.
77
78 master^ --> #1 --> #2 --> #3
79 \ *"pu" head
80 \---> master --> #1' --> #2' --> #3'
81
82The diff between master^ and #1 is applied to master and
83committed to create #1' commit with the commit information (log,
84author and date) taken from commit #1. On top of that #2' and #3'
85commits are made similarly out of #2 and #3 commits.
86
87Old #3 is not recorded in any of the .git/refs/heads/ file
88anymore, so after doing this you will have dangling commit if
89you ran fsck-cache, which is normal. After testing "pu", you
90can run "git prune" to get rid of those original three commits.
91
92While I am talking about "git rebase", I should talk about how
93to do cherrypicking using only the core GIT tools.
94
95Let's go back to the earlier picture, with different labels.
96
97You, as an individual developer, cloned upstream repository and
22a06b3c 98made a couple of commits on top of it.
365a00a3
RA
99
100 *your "master" head
101 upstream --> #1 --> #2 --> #3
102
103You would want changes #2 and #3 incorporated in the upstream,
104while you feel that #1 may need further improvements. So you
105prepare #2 and #3 for e-mail submission.
106
107 $ git format-patch master^^ master
108
917a8f89 109This creates two files, 0001-XXXX.patch and 0002-XXXX.patch. Send
365a00a3 110them out "To: " your project maintainer and "Cc: " your mailing
215a7ad1 111list. You could use contributed script git-send-email if
365a00a3
RA
112your host has necessary perl modules for this, but your usual
113MUA would do as long as it does not corrupt whitespaces in the
114patch.
115
116Then you would wait, and you find out that the upstream picked
117up your changes, along with other changes.
118
119 where *your "master" head
120 upstream --> #1 --> #2 --> #3
121 used \
122 to be \--> #A --> #2' --> #3' --> #B --> #C
123 *upstream head
124
125The two commits #2' and #3' in the above picture record the same
126changes your e-mail submission for #2 and #3 contained, but
addf88e4 127probably with the new sign-off line added by the upstream
365a00a3
RA
128maintainer and definitely with different committer and ancestry
129information, they are different objects from #2 and #3 commits.
130
131You fetch from upstream, but not merge.
132
133 $ git fetch upstream
134
135This leaves the updated upstream head in .git/FETCH_HEAD but
136does not touch your .git/HEAD nor .git/refs/heads/master.
137You run "git rebase" now.
138
139 $ git rebase FETCH_HEAD master
140
141Earlier, I said that rebase applies all the commits from your
142branch on top of the upstream head. Well, I lied. "git rebase"
143is a bit smarter than that and notices that #2 and #3 need not
144be applied, so it only applies #1. The commit ancestry graph
145becomes something like this:
146
147 where *your old "master" head
148 upstream --> #1 --> #2 --> #3
149 used \ your new "master" head*
150 to be \--> #A --> #2' --> #3' --> #B --> #C --> #1'
151 *upstream
152 head
153
154Again, "git prune" would discard the disused commits #1-#3 and
155you continue on starting from the new "master" head, which is
156the #1' commit.
157
158-jc
159
160-
161To unsubscribe from this list: send the line "unsubscribe git" in
162the body of a message to majordomo@vger.kernel.org
163More majordomo info at http://vger.kernel.org/majordomo-info.html
164
165