Re: request for documentation about branch surgery

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 7, 2009, 02:50 UTC
Message-ID: <7vab3hb40x.fsf@alter.siamese.dyndns.org>
In-Reply-To: <200907070105.12821.bruno@clisp.org>

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 ;-)

Show 9 quoted lines

>   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.

Show 6 quoted lines

> 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}

Show 8 quoted lines

> 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.