Re: request for documentation about branch surgery

From: Bruno Haible <bruno@clisp.org>
Date: Jul 7, 2009, 09:51 UTC
Message-ID: <200907071151.03567.bruno@clisp.org>
In-Reply-To: <51419b2c0907061930k71e20b42rb347b9ab8923e437@mail.gmail.com>

Hi Elijah,

> When the cost of certain activities changes dramatically (which git
> does by making lots new things possible and fast), formerly "exotic"
> usecases can become natural and common -- and really helpful.

Yes. With cvs, I would not never have dared to do branch surgery. With
git, I can - assuming some documentation. "git clone", "git checkout",
"git commit" each serves a particular purpose, so one can understand
when to use which command. But for branch surgery, several commands
are available:
  - "git reset --hard"
  - "git rebase"
  - "git rebase --onto"
  - "git merge" (simple case, no merge commit)
The mapping from "How do I ..." questions to command is not easy,
therefore a user's manual like
  <http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#rewriting-one-commit>
is needed.

Thanks for correcting me and showing simpler alternatives to what I said.

Still, can someone please extend the cited chapter of the user's manual,
so that it answers these questions?
  - How do I change the last commit in a branch?       [DONE]
  - How do I change an older commit in a branch?       [DONE]
  - How do I insert some commits between other commits in a branch?
                                                       [TODO]
  - How do I reorder commits in a branch?              [TODO - mention "git rebase -i"]
  - How do I copy selected commits from a branch to another?
                                                       [DONE]
  - How do I cut a branch?                             [TODO]
  - How do I replace a branch tip with the contents of another branch?
                                                       [TODO]
  - How do I reconnect a branch to another branch point?
                                                       [TODO]

> I think
> the rebase command would be much easier to understand for new users if
> it used an "--against" before the first reference(*).

Don't know, this is just a cosmetic change. The thing that confused me about "git rebase" is that its thinking is focused on the current branch. Whereas when I'm doing branch surgery, I'm creating a new branch bottom-up, so my thinking is "here I have some commits, what can I do with them". It requires a good user's manual to map this to the right "git rebase" command.

Bruno