[RFC/PATCH 2/1] fixup! Documentation: start to explain what git replace is for

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Jan 14, 2011, 08:49 UTC
Message-ID: <20110114084903.GD11343@burratino>
In-Reply-To: <loom.20110112T232501-316@post.gmane.org>

Some tweaks suggested by Maaartin:

- use a transliteration for Aleksey's name.  
- clarify that there will only be one parentless commit in a typical
  branch
- use variables so the recipe is easier to test by copy and paste
- remove unintended "-i" argument to sed

While at it, make a few miscellaneous grammar tweaks and make sure each line of the example raw commit appears on a separate line. The formatting is still not great for that --- there is too much space between lines.

Still to do: check whether this actually works and add a test script to make sure it keeps working.

Improved-by: Maaartin <grajcar1@seznam.cz>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
Can be tested with

	make -C Documentation git-replace.1
	man Documentation/git-replace.1

Maaartin wrote:

> Jonathan Nieder writes:

[side note: please do not prune the cc list; I only stumbled on this message in the online archive by luck]

Show 5 quoted lines

>> +. The following example comes from ??????? ??????:
>
> I know unicode exists already for many years, but in cygwin I get just a bunch 
> of question marks instead of the name. So I'd suggest to replace "Алексей 
> Шумкин" by "Alexej Shumkin" or whatever his preferred transcription is.

Makes sense.

>> +<1> Find all parentless commits in the 'master' branch;
>> +for 'master' read the branch holding v2.5 history.
>
> Aren't you later calling it "FIRST" and assuming there's only one?

Hmm. I want to say that there _could_ be multiple parentless commits in the v2.5 history and we are treating one of them as its root (just like git master has multiple parentless ancestors but e83c5163 is conventionally considered its beginning). Not sure how to write that clearly.

> Isn't the combination of "-i" (=in-place edit) with redirection wrong?

Good catch (the "-i" is a typo).

Show 5 quoted lines

> +$ objectId=$(git hash-object -t commit -w new)
> +$ git replace FIRST $objectId
>
> This is easier for people just willing to use it without much thinking, and 
> also for those having no idea that git-hash-object creates a new object.

Right, thanks.

 Documentation/git-replace.txt |   40 ++++++++++++++++++++++------------------
 1 files changed, 22 insertions(+), 18 deletions(-)

diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt
index 02e5de8..5829901 100644
--- a/Documentation/git-replace.txt
+++ b/Documentation/git-replace.txt
@@ -68,16 +68,17 @@ $ git cat-file commit foo                      <3>
 <2> show information about the true commit 'foo'
 <3> show information about the replacement commit 'bar'
 
-. The following example comes from Алексей Шумкин:
+. The following example comes from Aleksey Shumkin:
 +
 1.5 years ago I had sources of a project in another version control
 system.  And I had two branches: v2.4 and v2.5.
-They differed enough at that moment and laid in two different folders.
+They differed enough at that moment and lay in two different folders.
 Then I learned about Git and I decided to try to use this DVCS.
 I created two git repositories: one for each branch.
-So v2.4 has its own git repo and v2.5 (and above) has another one.
+So v2.4 has one git repo and v2.5 (and above) has another one.
 +
-Now I'd like to merge them as v2.5 was a continuous branch from v2.4,
+Now I'd like to merge them as if v2.5 were a continuous development
+from v2.4,
 but without rebasing (i.e. without a global change to the v2.5
 repository, which already has other branches).  It should look like
 the last commit of from the v2.4 branch is a parent of the first
@@ -89,25 +90,28 @@ use the more modern replace mechanism.  Below are untested step-by-step
 instructions.
 +
 --------------------------------------------------
-$ git rev-list master --parents | grep -v ' '    <1>
-$ git rev-parse v2.4                             <2>
-$ git cat-file commit FIRST >tmp                 <3>
-$ sed -i "/^tree / a \\
-parent $(git rev-parse v2.4)" <tmp >new          <4>
-$ git hash-object -t commit -w new               <5>
-$ git replace FIRST <object id from hash-object> <6>
-$ git show FIRST
-$ git log --graph --oneline -3 FIRST             <7>
+$ git rev-list master --parents | grep -v ' '
+$ first=$(git rev-list master --parents | grep -v ' ') <1>
+$ git rev-parse v2.4                                   <2>
+$ git cat-file commit $first >tmp                      <3>
+$ sed "/^tree / a \\
+parent $(git rev-parse v2.4)" <tmp >new                <4>
+$ new_commit=$(git hash-object -t commit -w new)       <5>
+$ git replace $first $new_commit                       <6>
+$ git show $first
+$ git log --graph --oneline -3 $first                  <7>
 --------------------------------------------------
 +
-<1> Find all parentless commits in the 'master' branch;
-for 'master' read the branch holding v2.5 history.
+<1> List all parentless commits in the 'master' branch and
+call the appropriate one (in this case the only one) $first.
+Instead of 'master' one would use the branch holding v2.5
+history.
 <2> Find the last commit of v2.4.
 <3> Save the current state of the first commit of v2.5 to a file.
 <4> Edit this file, adding 'parent' line between 'tree' and 'author'
-headers, so the header of this file looks like the following:
-  tree 13d050266e05f7c66000240814199fcf3b559d43
-  parent ada9983c4256f5a7bac1f7f0e29d52011741d6aa
+headers, so the header of this file looks like the following: +
+  tree 13d050266e05f7c66000240814199fcf3b559d43 +
+  parent ada9983c4256f5a7bac1f7f0e29d52011741d6aa +
   author Jakub Narebski <jnareb@gmail.com> 1294231771 +0100
 <5> Add the newly created object to the repository.
 <6> Use it as a replacement.

-- 
1.7.4.rc2