docs: adjust the technical overview for the rename `pu` -> `seen`
This patch tries to rewrite history a bit: the mail contents that have been added to Git's source code are actually fixed, we cannot change them in hindsight. But as the `pu` branch _was_ renamed, and as the documents were added to Git's source code not so much as historical record, but to describe the status quo, let's pretend that we have a time machine and adjust the provided information accordingly. Where appropriate, quotes were added for readability. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Johannes Schindelin committed
Jun 25, 2020 at 12:18 UTC
77dc6049c3ba7511c398428824a53bcb201cc005
4 files changed
+61
-61
Documentation/howto/maintain-git.txt
+26
-26
@@ -66,7 +66,7 @@ this mailing list after each feature release is made.
66
demonstrated to be regression free. New changes are tested
67
in 'next' before merged to 'master'.
68
69
- - 'pu' branch is used to publish other proposed changes that do
69
+ - 'seen' branch is used to publish other proposed changes that do
70
not yet pass the criteria set for 'next'.
71
72
- The tips of 'master' and 'maint' branches will not be rewound to
@@ -76,7 +76,7 @@ this mailing list after each feature release is made.
76
of the cycle.
77
78
- Usually 'master' contains all of 'maint' and 'next' contains all
79
- of 'master'. 'pu' contains all the topics merged to 'next', but
79
+ of 'master'. 'seen' contains all the topics merged to 'next', but
80
is rebuilt directly on 'master'.
81
82
- The tip of 'master' is meant to be more stable than any
@@ -211,12 +211,12 @@ by doing the following:
211
series?)
212
213
- Prepare 'jch' branch, which is used to represent somewhere
214
- between 'master' and 'pu' and often is slightly ahead of 'next'.
214
+ between 'master' and 'seen' and often is slightly ahead of 'next'.
215
216
- $ Meta/Reintegrate master..pu >Meta/redo-jch.sh
216
+ $ Meta/Reintegrate master..seen >Meta/redo-jch.sh
217
218
The result is a script that lists topics to be merged in order to
219
- rebuild 'pu' as the input to Meta/Reintegrate script. Remove
219
+ rebuild 'seen' as the input to Meta/Reintegrate script. Remove
220
later topics that should not be in 'jch' yet. Add a line that
221
consists of '### match next' before the name of the first topic
222
in the output that should be in 'jch' but not in 'next' yet.
@@ -273,29 +273,29 @@ by doing the following:
273
merged to 'master'. This may lose '### match next' marker;
274
add it again to the appropriate place when it happens.
275
276
- - Rebuild 'pu'.
276
+ - Rebuild 'seen'.
277
278
- $ Meta/Reintegrate master..pu >Meta/redo-pu.sh
278
+ $ Meta/Reintegrate master..seen >Meta/redo-seen.sh
279
280
- Edit the result by adding new topics that are not still in 'pu'
280
+ Edit the result by adding new topics that are not still in 'seen'
281
in the script. Then
282
283
- $ git checkout -B pu jch
284
- $ sh Meta/redo-pu.sh
283
+ $ git checkout -B seen jch
284
+ $ sh Meta/redo-seen.sh
285
286
- When all is well, clean up the redo-pu.sh script with
286
+ When all is well, clean up the redo-seen.sh script with
287
288
- $ sh Meta/redo-pu.sh -u
288
+ $ sh Meta/redo-seen.sh -u
289
290
Double check by running
291
292
- $ git branch --no-merged pu
292
+ $ git branch --no-merged seen
293
294
to see there is no unexpected leftover topics.
295
296
At this point, build-test the result for semantic conflicts, and
297
if there are, prepare an appropriate merge-fix first (see
298
- appendix), and rebuild the 'pu' branch from scratch, starting at
298
+ appendix), and rebuild the 'seen' branch from scratch, starting at
299
the tip of 'jch'.
300
301
- Update "What's cooking" message to review the updates to
@@ -305,14 +305,14 @@ by doing the following:
305
306
$ Meta/cook
307
308
- This script inspects the history between master..pu, finds tips
308
+ This script inspects the history between master..seen, finds tips
309
of topic branches, compares what it found with the current
310
contents in Meta/whats-cooking.txt, and updates that file.
311
- Topics not listed in the file but are found in master..pu are
311
+ Topics not listed in the file but are found in master..seen are
312
added to the "New topics" section, topics listed in the file that
313
- are no longer found in master..pu are moved to the "Graduated to
313
+ are no longer found in master..seen are moved to the "Graduated to
314
master" section, and topics whose commits changed their states
315
- (e.g. used to be only in 'pu', now merged to 'next') are updated
315
+ (e.g. used to be only in 'seen', now merged to 'next') are updated
316
with change markers "<<" and ">>".
317
318
Look for lines enclosed in "<<" and ">>"; they hold contents from
@@ -342,7 +342,7 @@ Observations
342
Some observations to be made.
343
344
* Each topic is tested individually, and also together with other
345
- topics cooking first in 'pu', then in 'jch' and then in 'next'.
345
+ topics cooking first in 'seen', then in 'jch' and then in 'next'.
346
Until it matures, no part of it is merged to 'master'.
347
348
* A topic already in 'next' can get fixes while still in
@@ -385,7 +385,7 @@ new use of the variable under its old name. When these two topics
385
are merged together, the reference to the variable newly added by
386
the latter topic will still use the old name in the result.
387
388
-The Meta/Reintegrate script that is used by redo-jch and redo-pu
388
+The Meta/Reintegrate script that is used by redo-jch and redo-seen
389
scripts implements a crude but usable way to work this issue around.
390
When the script merges branch $X, it checks if "refs/merge-fix/$X"
391
exists, and if so, the effect of it is squashed into the result of
@@ -405,14 +405,14 @@ commit that can be squashed into a result of mechanical merge to
405
correct semantic conflicts.
406
407
After finding that the result of merging branch "ai/topic" to an
408
-integration branch had such a semantic conflict, say pu~4, check the
408
+integration branch had such a semantic conflict, say seen~4, check the
409
problematic merge out on a detached HEAD, edit the working tree to
410
fix the semantic conflict, and make a separate commit to record the
411
fix-up:
412
413
- $ git checkout pu~4
413
+ $ git checkout seen~4
414
$ git show -s --pretty=%s ;# double check
415
- Merge branch 'ai/topic' to pu
415
+ Merge branch 'ai/topic' to seen
416
$ edit
417
$ git commit -m 'merge-fix/ai/topic' -a
418
@@ -424,9 +424,9 @@ result:
424
Then double check the result by asking Meta/Reintegrate to redo the
425
merge:
426
427
- $ git checkout pu~5 ;# the parent of the problem merge
427
+ $ git checkout seen~5 ;# the parent of the problem merge
428
$ echo ai/topic | Meta/Reintegrate
429
- $ git diff pu~4
429
+ $ git diff seen~4
430
431
This time, because you prepared refs/merge-fix/ai/topic, the
432
resulting merge should have been tweaked to include the fix for the
@@ -438,7 +438,7 @@ branch needs this merge-fix is because another branch merged earlier
438
to the integration branch changed the underlying assumption ai/topic
439
branch made (e.g. ai/topic branch added a site to refer to a
440
variable, while the other branch renamed that variable and adjusted
441
-existing use sites), and if you changed redo-jch (or redo-pu) script
441
+existing use sites), and if you changed redo-jch (or redo-seen) script
442
to merge ai/topic branch before the other branch, then the above
443
merge-fix should not be applied while merging ai/topic, but should
444
instead be applied while merging the other branch. You would need
Documentation/howto/rebase-from-internal-branch.txt
+16
-16
@@ -4,7 +4,7 @@ Cc: Petr Baudis <pasky@suse.cz>, Linus Torvalds <torvalds@osdl.org>
4
Subject: Re: sending changesets from the middle of a git tree
5
Date: Sun, 14 Aug 2005 18:37:39 -0700
6
Abstract: In this article, JC talks about how he rebases the
7
- public "pu" branch using the core Git tools when he updates
7
+ public "seen" 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.
@@ -20,8 +20,8 @@ Petr Baudis <pasky@suse.cz> writes:
20
> where Junio C Hamano <junkio@cox.net> told me that...
21
>> Linus Torvalds <torvalds@osdl.org> writes:
22
>>
23
->> > Junio, maybe you want to talk about how you move patches from your "pu"
24
->> > branch to the real branches.
23
+>> > Junio, maybe you want to talk about how you move patches from your
24
+>> > "seen" branch to the real branches.
25
>>
26
> Actually, wouldn't this be also precisely for what StGIT is intended to?
27
--------------------------------------
@@ -33,12 +33,12 @@ the kind of task StGIT is designed to do.
33
I just have done a simpler one, this time using only the core
34
Git tools.
35
36
-I had a handful of commits that were ahead of master in pu, and I
36
+I had a handful of commits that were ahead of master in 'seen', and I
37
wanted to add some documentation bypassing my usual habit of
38
-placing new things in pu first. At the beginning, the commit
38
+placing new things in 'seen' first. At the beginning, the commit
39
ancestry graph looked like this:
40
41
- *"pu" head
41
+ *"seen" head
42
master --> #1 --> #2 --> #3
43
44
So I started from master, made a bunch of edits, and committed:
@@ -50,7 +50,7 @@ So I started from master, made a bunch of edits, and committed:
50
51
After the commit, the ancestry graph would look like this:
52
53
- *"pu" head
53
+ *"seen" head
54
master^ --> #1 --> #2 --> #3
55
\
56
\---> master
@@ -58,31 +58,31 @@ After the commit, the ancestry graph would look like this:
58
The old master is now master^ (the first parent of the master).
59
The new master commit holds my documentation updates.
60
61
-Now I have to deal with "pu" branch.
61
+Now I have to deal with "seen" branch.
62
63
This is the kind of situation I used to have all the time when
64
Linus was the maintainer and I was a contributor, when you look
65
-at "master" branch being the "maintainer" branch, and "pu"
65
+at "master" branch being the "maintainer" branch, and "seen"
66
branch being the "contributor" branch. Your work started at the
67
tip of the "maintainer" branch some time ago, you made a lot of
68
progress in the meantime, and now the maintainer branch has some
69
other commits you do not have yet. And "git rebase" was written
70
with the explicit purpose of helping to maintain branches like
71
-"pu". You _could_ merge master to pu and keep going, but if you
71
+"seen". You _could_ merge master to 'seen' and keep going, but if you
72
eventually want to cherrypick and merge some but not necessarily
73
all changes back to the master branch, it often makes later
74
operations for _you_ easier if you rebase (i.e. carry forward
75
-your changes) "pu" rather than merge. So I ran "git rebase":
75
+your changes) "seen" rather than merge. So I ran "git rebase":
76
77
- $ git checkout pu
78
- $ git rebase master pu
77
+ $ git checkout seen
78
+ $ git rebase master seen
79
80
What this does is to pick all the commits since the current
81
-branch (note that I now am on "pu" branch) forked from the
81
+branch (note that I now am on "seen" branch) forked from the
82
master branch, and forward port these changes.
83
84
master^ --> #1 --> #2 --> #3
85
- \ *"pu" head
85
+ \ *"seen" head
86
\---> master --> #1' --> #2' --> #3'
87
88
The diff between master^ and #1 is applied to master and
@@ -92,7 +92,7 @@ commits are made similarly out of #2 and #3 commits.
92
93
Old #3 is not recorded in any of the .git/refs/heads/ file
94
anymore, so after doing this you will have dangling commit if
95
-you ran fsck-cache, which is normal. After testing "pu", you
95
+you ran fsck-cache, which is normal. After testing "seen", you
96
can run "git prune" to get rid of those original three commits.
97
98
While I am talking about "git rebase", I should talk about how
Documentation/howto/revert-branch-rebase.txt
+16
-16
@@ -15,7 +15,7 @@ One of the changes I pulled into the 'master' branch turns out to
15
break building Git with GCC 2.95. While they were well-intentioned
16
portability fixes, keeping things working with gcc-2.95 was also
17
important. Here is what I did to revert the change in the 'master'
18
-branch and to adjust the 'pu' branch, using core Git tools and
18
+branch and to adjust the 'seen' branch, using core Git tools and
19
barebone Porcelain.
20
21
First, prepare a throw-away branch in case I screw things up.
@@ -104,11 +104,11 @@ $ git diff master..revert-c99
104
105
says nothing.
106
107
-Then we rebase the 'pu' branch as usual.
107
+Then we rebase the 'seen' branch as usual.
108
109
------------------------------------------------
110
-$ git checkout pu
111
-$ git tag pu-anchor pu
110
+$ git checkout seen
111
+$ git tag seen-anchor seen
112
$ git rebase master
113
* Applying: Redo "revert" using three-way merge machinery.
114
First trying simple merge strategy to cherry-pick.
@@ -127,11 +127,11 @@ First trying simple merge strategy to cherry-pick.
127
First trying simple merge strategy to cherry-pick.
128
------------------------------------------------
129
130
-The temporary tag 'pu-anchor' is me just being careful, in case 'git
130
+The temporary tag 'seen-anchor' is me just being careful, in case 'git
131
rebase' screws up. After this, I can do these for sanity check:
132
133
------------------------------------------------
134
-$ git diff pu-anchor..pu ;# make sure we got the master fix.
134
+$ git diff seen-anchor..seen ;# make sure we got the master fix.
135
$ make CC=gcc-2.95 clean test ;# make sure it fixed the breakage.
136
$ make clean test ;# make sure it did not cause other breakage.
137
------------------------------------------------
@@ -140,7 +140,7 @@ Everything is in the good order. I do not need the temporary branch
140
or tag anymore, so remove them:
141
142
------------------------------------------------
143
-$ rm -f .git/refs/tags/pu-anchor
143
+$ rm -f .git/refs/tags/seen-anchor
144
$ git branch -d revert-c99
145
------------------------------------------------
146
@@ -168,18 +168,18 @@ Committed merge 7fb9b7262a1d1e0a47bbfdcbbcf50ce0635d3f8f
168
And the final repository status looks like this:
169
170
------------------------------------------------
171
-$ git show-branch --more=1 master pu rc
171
+$ git show-branch --more=1 master seen rc
172
! [master] Revert "Replace zero-length array decls with []."
173
- ! [pu] git-repack: Add option to repack all objects.
173
+ ! [seen] git-repack: Add option to repack all objects.
174
* [rc] Merge refs/heads/master from .
175
---
176
- + [pu] git-repack: Add option to repack all objects.
177
- + [pu~1] More documentation updates.
178
- + [pu~2] Show commits in topo order and name all commits.
179
- + [pu~3] mailinfo and applymbox updates
180
- + [pu~4] Document "git cherry-pick" and "git revert"
181
- + [pu~5] Remove git-apply-patch-script.
182
- + [pu~6] Redo "revert" using three-way merge machinery.
176
+ + [seen] git-repack: Add option to repack all objects.
177
+ + [seen~1] More documentation updates.
178
+ + [seen~2] Show commits in topo order and name all commits.
179
+ + [seen~3] mailinfo and applymbox updates
180
+ + [seen~4] Document "git cherry-pick" and "git revert"
181
+ + [seen~5] Remove git-apply-patch-script.
182
+ + [seen~6] Redo "revert" using three-way merge machinery.
183
- [rc] Merge refs/heads/master from .
184
++* [master] Revert "Replace zero-length array decls with []."
185
- [rc~1] Merge refs/heads/master from .
Documentation/howto/update-hook-example.txt
+3
-3
@@ -179,7 +179,7 @@ allowed-groups, to describe which heads can be pushed into by
179
whom. The format of each file would look like this:
180
181
refs/heads/master junio
182
- +refs/heads/pu junio
182
+ +refs/heads/seen junio
183
refs/heads/cogito$ pasky
184
refs/heads/bw/.* linus
185
refs/heads/tmp/.* .*
@@ -187,6 +187,6 @@ whom. The format of each file would look like this:
187
188
With this, Linus can push or create "bw/penguin" or "bw/zebra"
189
or "bw/panda" branches, Pasky can do only "cogito", and JC can
190
-do master and pu branches and make versioned tags. And anybody
191
-can do tmp/blah branches. The '+' sign at the pu record means
190
+do master and "seen" branches and make versioned tags. And anybody
191
+can do tmp/blah branches. The '+' sign at the "seen" record means
192
that JC can make non-fast-forward pushes on it.