Re: [PATCH v2 05/15] user-manual: Add a few references to 'git rebase -i'

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

"W. Trevor King" <wking@tremily.us> writes:

> From: "W. Trevor King" <wking@tremily.us>
>
> I think this interface is much more convenient than extended cherry
> picking or using 'git format-patch'.  Inserting a number of references
> should raise awareness among new users.  The previously discussed
> methods (cherry picking and format-patch-ing) are still useful,
> because all of these approaches have the same effect, which may help
> demystify the process for newbies.
>
> Signed-off-by: W. Trevor King <wking@tremily.us>
> ---
>  Documentation/user-manual.txt | 21 +++++++++++++++++----
>  1 file changed, 17 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index a8f792d..5d80b40 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -2532,6 +2532,13 @@ return mywork to the state it had before you started the rebase:
>  $ git rebase --abort
>  -------------------------------------------------
>  
> +If you need to reorder or edit a number of commits in a branch, it may
> +be easier to use `git rebase -i`, which allows you to reorder and
> +squash commits, as well as marking them for individual editing during
> +the rebase.  See linkgit:git-rebase[1] for details, and
> +<<reordering-patch-series>> for alternatives.
> +
> +

This change is very good (modulo the extra blank line at the end).

>  [[rewriting-one-commit]]
>  Rewriting a single commit
>  -------------------------
> @@ -2546,10 +2553,10 @@ $ git commit --amend
>  which will replace the old commit by a new commit incorporating your
>  changes, giving you a chance to edit the old commit message first.
>  
> -You can also use a combination of this and linkgit:git-rebase[1] to
> -replace a commit further back in your history and recreate the
> -intervening changes on top of it.  First, tag the problematic commit
> -with
> +You can also use a combination of `commit --amend` and
> +linkgit:git-rebase[1] (see <<using-git-rebase>>) to replace a commit
> +further back in your history and recreate the intervening changes on
> +top of it.  First, tag the problematic commit with

I think this section can use a lot more love.  There is no reason to
have "bad" tag (tagging the tip of mywork might have made sense in
the old days without detached HEAD or reflog), for example.

Alternatively, we can explain only the amending of the tip commit in
this section, removing everything else; I think that is probably a
better option.  The series of sections around here would then look
like:

 * The section before this talked about a straight-forward "rebase";

 * This section then talks about "commit --amend", nothing else;

 * The next section talks about taking "format-patch A..B", flipping
   its output around and applying to A.  Enhance that section with
   the material to be removed from here, which talks about applying
   "format-patch A..B" on top of the amended A.

 * Then add a separate section after that "Reordering or selecting
   from a patch series" section to discuss "rebase -i".

Hmm?

>  -------------------------------------------------
>  $ git tag bad mywork~5
> @@ -2584,6 +2591,12 @@ new commits having new object names.
>  Reordering or selecting from a patch series
>  -------------------------------------------
>  
> +There are a number of ways you can go about editing an existing patch
> +series.  The easiest way is probably by using `git rebase -i`,
> +mentioned in <<using-git-rebase>>, but whether you use
> +linkgit:git-rebase[1] or one of the methods discussed below, the
> +effect is the same.  Pick whichever approach you like best.
> +
>  Given one existing commit, the linkgit:git-cherry-pick[1] command
>  allows you to apply the change introduced by that commit and create a
>  new commit that records it.  So, for example, if "mywork" points to a