public inbox for git@vger.kernel.org 
 help / color / mirror / Atom feed

From: Bruno Haible <bruno@clisp•org>
To: git@vger•kernel.org
Subject: request for documentation about branch surgery
Date: Tue, 7 Jul 2009 01:05:12 +0200	[thread overview]
Message-ID: <200907070105.12821.bruno@clisp.org> (raw)

Hi,

Here are a few things that I would have expected to find in the Git user's
manual, chapter "Rewriting history and maintaining patch series"
  <http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#cleaning-up-history>

It is meant for a user who does not yet know about "git rebase", "git merge",
"git reset" and the like. Organized by the goal that a user has ("how do I?").


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. I found this sequence
of commands useful:

  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 A
    $ git branch temp
    $ git checkout temp
    [make changes for B]
    $ git commit -a

  now:

            A---C---...---Z    master
             \
              --B              temp

    $ git checkout master
    $ git rebase temp
    $ git branch -d temp


2) About the section "Reordering or selecting from a patch series".
   The "git rebase" documentation contains a good example:

   Reordering, possibly merging, the last 5 commits:
   $ git rebase -i HEAD~5
   See "man git-rebase" under "INTERACTIVE MODE".

   I find this technique very useful, because it guarantees that no
   commit gets lost (unlike "git cherry-pick"). Maybe the section could
   be split into two sections
      "Reordering a patch series"
   and
      "Selecting from a patch series"?


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.


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

   It goes like this:

     $ git checkout master
     $ git reset --hard E


5) Then, it would be good to have a section "Replacing branches"

   How do I copy the contents of a branch over to another branch, replacing
   the recent development on that branch?

  If you want to copy a branch into another, while throwing away commits:

                     F1---F2---F3                         released
                    /
               D---E---F---G---H---.........---Y---Z master

  =>
                     F1---F2---F3   released
                    /
               D---E---F1---F2---F3 master

  This is achieved by

    $ git checkout master
    $ git reset --hard E      # Cut the branch "master"
    $ git merge released      # Copy commits from branch "released" to "master"


6) Also, it would be good to have a section "Reconnecting branches after rebase".
   If you want to reconnect a branch to a rebased master, here's how to do it:

                   /--C'--...---P'--Q'--...---Z'  new rebased master
              A---B---C---...---P---Q---...---Z   old master
                                 \
                                  --BA---...---BZ  release-branch

  =>
              A---B---C'--...---P'--Q'--...---Z'  new rebased master
                                 \
                                  --BA---...---BZ  release-branch

  This is achieved by

    $ git checkout release-branch
    $ git rebase --onto P' P


This might seem exotic, but these use cases all came up while rewriting the
history after a "git cvsimport".

Bruno

next             reply	other threads:[~2009-07-06 23:05 UTC|newest]

Thread overview: 10+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2009-07-06 23:05 Bruno Haible [this message]
2009-07-07  2:30 ` request for documentation about branch surgery Elijah Newren
2009-07-07  3:45   ` Elijah Newren
2009-07-07  9:51   ` Bruno Haible
2009-07-07 10:06     ` Andreas Ericsson
2009-07-07  2:50 ` Junio C Hamano
2009-07-07 10:13   ` Bruno Haible
2009-07-07 11:03     ` Andreas Ericsson
2009-07-07 15:52     ` Junio C Hamano
2009-07-07 18:28 ` Daniel Barkalow

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=200907070105.12821.bruno@clisp.org \
    --to=bruno@clisp$(echo .)org \
    --cc=git@vger$(echo .)kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox