Re: [RFC/PATCH 1/2] Doc rebase: Describe rebase as excluding merge commits
"Philip Oakley" writes: > From: "Junio C Hamano" > Sent: Monday, May 20, 2013 5:43 AM >> Jonathan Nieder writes: >> >>> Philip Oakley wrote: >>> Describe rebase in the description section. >>> >>> It already does that. :) I think you mean "start with a summary", >>> which is a valuable improvement. >> >> It indeed is a good idea to give the "high-level introduction" at >> the very beginning, but I do not think it should describe only one >> of the three major modes of "git rebase" (i.e. no -m, no -i), like >> the proposed patch text does. We should instead say what it is used >> for and why the user would want to use it that is common across >> these modes at a very high level. > > That would repeat the NAME issue (of trying too hard to be exact & > precise). This introductory text is that "summary". If that is "summary", it should never talk about "skips merges", which only applies to the mode without -m, no? The highest level view of what the command is for (the motivation why the user would want to consider learning how to use the command) is "You have a history built on top of some commit, and you want to rebuild the history on top of another commit, e.g. you earlier built on the tip of a branch that has some other work, and you want to rebuild the history on top of the updated tip of that other branch". The details of how the history is "rebuilt" can differ while using various modes of operation. Some may skip merges, some may try to preserve the topology, some may even let you insert new commits by letting you tell it to stop in the middle. That is not "summary" but is part of mode specific description. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [RFC/PATCH 1/2] Doc rebase: Describe rebase as excluding merge commits
From: "Junio C Hamano" Sent: Monday, May 20, 2013 5:43 AM Jonathan Nieder writes: Philip Oakley wrote: Describe rebase in the description section. It already does that. :) I think you mean "start with a summary", which is a valuable improvement. It indeed is a good idea to give the "high-level introduction" at the very beginning, but I do not think it should describe only one of the three major modes of "git rebase" (i.e. no -m, no -i), like the proposed patch text does. We should instead say what it is used for and why the user would want to use it that is common across these modes at a very high level. That would repeat the NAME issue (of trying too hard to be exact & precise). This introductory text is that "summary". The patch 2/2 should be the one for the extra detail of the various whys and wherefores - at least that was my intent. DESCRIPTION --- token mention of *why* a user would want to use it (e.g., "so that the patches apply cleanly to their new base").> Exactly. -- -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [RFC/PATCH 1/2] Doc rebase: Describe rebase as excluding merge commits
Jonathan Nieder writes: > Philip Oakley wrote: > >> Describe rebase in the description section. > > It already does that. :) I think you mean "start with a summary", > which is a valuable improvement. It indeed is a good idea to give the "high-level introduction" at the very beginning, but I do not think it should describe only one of the three major modes of "git rebase" (i.e. no -m, no -i), like the proposed patch text does. We should instead say what it is used for and why the user would want to use it that is common across these modes at a very high level. > DESCRIPTION > --- > mention of *why* a user would want to use it (e.g., "so that the patches > apply cleanly to their new base").> Exactly. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [RFC/PATCH 1/2] Doc rebase: Describe rebase as excluding merge commits
From: "Jonathan Nieder"
Sent: Sunday, May 19, 2013 7:08 PM
Philip Oakley wrote:
Describe rebase in the description section.
It already does that. :) I think you mean "start with a summary",
which is a valuable improvement.
Yes.
Include a softer paraphrased version from the crytic, well-loved,
but sometimes parodied, Name description, and tell users that merge
commits are excluded by default.
I don't really follow this paragraph. Are you saying "The NAME line
is cryptic, but let's copy it anyway, since it is better than
nothing"?
I was keeping the 'cryptic/esoteric' NAME line, because it is commented
on in a few blogs [1]. It is accurate but let's not spoil those blogs...
The fundamental reason for the update was to introduce 'somewhere' in
the text the "excluding merge commits by default" note, and I couldn't
find an easy way of updating the NAME line, and then realised a softer
introduction wiould kill two birds with one stone.
[...]
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -16,6 +16,10 @@ SYNOPSIS
DESCRIPTION
---
+'git rebase' will transfer local commits, excluding merge commits
+by default, to the head of the branch's upstream, or onto a new base
+if given.
+
Not about this patch, but some day it would be nice to standardize on
one tense for the DESCRIPTION sections of manpages. Some git commands
use the imperative ("Reply local commits, excluding merge commits, on
top of ..."), some use the present indicative ("Replays local commits,
excluding merge commits, ..."), and some use the future ("Will replay
local commits, excluding merge commits, ...").
The traditional tense for Unix manpages is the present indicative.
But you are right to match the rest of the description here.
If is specified, 'git rebase' will perform an automatic
`git checkout ` before doing anything else. Otherwise
it remains on the current branch.
The description has become very long by now. I wonder if it's
possible to break it into chunks, like so?
DESCRIPTION
---
mention of *why* a user would want to use it (e.g., "so that the
patches
apply cleanly to their new base").>
It proceeds using the following steps:
1. If is specified, ...
2. Decides which commits will need to be applied.
These are plain, non-merge commits that are ancestors of HEAD but
not of .
3. Checks out . ()
4. Reapplies the commits listed on step (2), one by one, in order.
If merge failures are encountered, the program will exit and allow
the user to resolve them and resume or cancel the rebase. See
the RESPONDING TO MERGE CONFLICTS section below for details.
5. Once all of the commits from step (2) have been applied, updates
to point to the new HEAD.
The result is an updated that ...
OPTIONS
---
...
EXAMPLES
Assume the following history exists and the current branch is "topic":
...
Description of specific options like "--preserve-merges" and "--onto"
could move out of the DESCRIPTION section and to the OPTIONS section.
What do you think?
It's probably something I'd need help on (to ensure correctness). I'll
have a go based on your suggestions in the next few days.
Thanks,
Jonathan
--
[1] http://steveko.wordpress.com/2012/02/24/10-things-i-hate-about-git/
section 3 'update'.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [RFC/PATCH 1/2] Doc rebase: Describe rebase as excluding merge commits
Philip Oakley wrote:
> Describe rebase in the description section.
It already does that. :) I think you mean "start with a summary",
which is a valuable improvement.
> Include a softer paraphrased version from the crytic, well-loved,
> but sometimes parodied, Name description, and tell users that merge
> commits are excluded by default.
I don't really follow this paragraph. Are you saying "The NAME line
is cryptic, but let's copy it anyway, since it is better than nothing"?
[...]
> --- a/Documentation/git-rebase.txt
> +++ b/Documentation/git-rebase.txt
> @@ -16,6 +16,10 @@ SYNOPSIS
>
> DESCRIPTION
> ---
> +'git rebase' will transfer local commits, excluding merge commits
> +by default, to the head of the branch's upstream, or onto a new base
> +if given.
> +
Not about this patch, but some day it would be nice to standardize on
one tense for the DESCRIPTION sections of manpages. Some git commands
use the imperative ("Reply local commits, excluding merge commits, on
top of ..."), some use the present indicative ("Replays local commits,
excluding merge commits, ..."), and some use the future ("Will replay
local commits, excluding merge commits, ...").
The traditional tense for Unix manpages is the present indicative.
But you are right to match the rest of the description here.
> If is specified, 'git rebase' will perform an automatic
> `git checkout ` before doing anything else. Otherwise
> it remains on the current branch.
The description has become very long by now. I wonder if it's
possible to break it into chunks, like so?
DESCRIPTION
---
It proceeds using the following steps:
1. If is specified, ...
2. Decides which commits will need to be applied.
These are plain, non-merge commits that are ancestors of HEAD but
not of .
3. Checks out . ()
4. Reapplies the commits listed on step (2), one by one, in order.
If merge failures are encountered, the program will exit and allow
the user to resolve them and resume or cancel the rebase. See
the RESPONDING TO MERGE CONFLICTS section below for details.
5. Once all of the commits from step (2) have been applied, updates
to point to the new HEAD.
The result is an updated that ...
OPTIONS
---
...
EXAMPLES
Assume the following history exists and the current branch is "topic":
...
Description of specific options like "--preserve-merges" and "--onto"
could move out of the DESCRIPTION section and to the OPTIONS section.
What do you think?
Thanks,
Jonathan
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[RFC/PATCH 1/2] Doc rebase: Describe rebase as excluding merge commits
Describe rebase in the description section. Include a softer paraphrased version from the crytic, well-loved, but sometimes parodied, Name description, and tell users that merge commits are excluded by default. Signed-off-by: Philip Oakley --- http://article.gmane.org/gmane.comp.version-control.git/217410 http://article.gmane.org/gmane.comp.version-control.git/217495 --- Documentation/git-rebase.txt | 4 1 file changed, 4 insertions(+) diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index aca8405..87a8095 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -16,6 +16,10 @@ SYNOPSIS DESCRIPTION --- +'git rebase' will transfer local commits, excluding merge commits +by default, to the head of the branch's upstream, or onto a new base +if given. + If is specified, 'git rebase' will perform an automatic `git checkout ` before doing anything else. Otherwise it remains on the current branch. -- 1.8.1.msysgit.1 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
