Re: request for documentation about branch surgery

[Junio C Hamano <gitster@pobox.com>]

Bruno Haible <bruno@clisp.org> writes:

> 1) After the section "Rewriting a single commit", it may be useful to
> have a section "Inserting one or more new commits". This is something that
> cannot be done with the "detached head" technique.

You learn new things every day, and today is such a day ;-)

>   If you want to add a commit in the middle of a branch:
>
>             A---C---...---Z    master
>
>   =>
>
>             A---B---C---...---Z    master
>
>   it is achieved by

        $ git checkout master~25 ;# detach HEAD at A
        $ edit edit edit
        $ git commit ;# creates B

which makes

               B              HEAD (detached)
              /
             A---C---...---Z    master

and then

        $ git rebase HEAD master

which reshapes the history into


               B---C'--...---Z' master
              /
             A---C---...---Z    master@{1}

and you are done.

> 3) When do I need "git merge", and when do I need "git rebase", in the
>    context of branch surgery?
>
>    The simple answer, that I would find worth mentioning, is:
>      - "git merge" copies commits from one branch to another.
>      - "git rebase" only moves commits around to make history more linear.

If you think "git merge" _copies_, you will never understand what "merge"
does.

If you have master and origin branch, merging them together

                X---Y---Z  origin
               /
              /
             O----A----B master

        $ git checkout master
        $ git merge origin

will give you this:


                X---Y---Z  origin
               /         \
              /           \
             O----A----B---M master
                       ^
                       master@{1}

There is no copying involved anywhere .  It only creates a new commit, M,
and that commit allows 'master' (that used to point at B) to reach both
the history leading to B and the history leading to Z.

On the other hand, rebase _copies_.  It _does_ make new commits A' and B',
whose _effect_ to the tree mimics those of A and B.

        $ git rebase origin master


                X---Y---Z---A'---B' master
               /        ^origin
              /
             O----A----B master@{1}

> 4) It would be good to have a section "Cutting branches"
>
>    How do I remove the N most recent commits from a branch?
>
>                D---E---F---G---H---.........---Y---Z master
>
>   =>
>                D---E master

And it is not even cutting.  It merely makes this:

                      F---G---H---.........---Y---Z master@{1}
                     /
                D---E
                    ^master

so that a new history can grow at E that is parallel to the
history that leads to Z.

I think your confusion is primarily coming from not understanding what a
branch in git is.  A branch in git does not have its own identity per-se,
and a commit does _not_ belong to a branch, in the sense that a commit
object does not record anywhere on which branch it was created on.  A
branch is just a pointer into a dag and the pointer can be moved.