From: Junio C Hamano <gitster@pobox•com>
To: Kaartic Sivaraam <kaartic.sivaraam@gmail•com>
Cc: Git mailing list <git@vger•kernel.org>
Subject: Re: [PATCH v2 0/3] rebase: give precise error message
Date: Wed, 29 Nov 2017 09:10:34 +0900 [thread overview]
Message-ID: <xmqqzi7654hx.fsf@gitster.mtv.corp.google.com> (raw)
In-Reply-To: <1511877882.10193.2.camel@gmail.com> (Kaartic Sivaraam's message of "Tue, 28 Nov 2017 19:34:42 +0530")
Kaartic Sivaraam <kaartic.sivaraam@gmail•com> writes:
> Something like the following diff with additional changes to other
> places that refer to <branch>,
>
> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
> index 67d48e688..ba4a545bf 100644
> --- a/Documentation/git-rebase.txt
> +++ b/Documentation/git-rebase.txt
> @@ -9,9 +9,9 @@ SYNOPSIS
> --------
> [verse]
> 'git rebase' [-i | --interactive] [options] [--exec <cmd>] [--onto <newbase>]
> - [<upstream> [<branch>]]
> + [<upstream> [<ref>]]
> 'git rebase' [-i | --interactive] [options] [--exec <cmd>] [--onto <newbase>]
> - --root [<branch>]
> + --root [<ref>]
> 'git rebase' --continue | --skip | --abort | --quit | --edit-todo
>
> DESCRIPTION
>
>
> If <ref> is the correct substitute <branch>, I could try to send a
> patch that fixes this.
I do not think the above is a good change in the first place for at
least two reasons. By saying <ref>, the updated text says "not just
branches but you can also give tags and remote-tracking branches".
In reality, however, it can take any commit-ish, as the "no we are
not rebasing the current checkout" form of the command is merely a
short-hand to check it out first [*1*]. It gives appearance that
the change is making it more broad, but not making it broad enough.
At the same time, more than 90% of the time, people give a branch
name there. Saying "branch-or-commit" for a short description of
the command line (which is what synopsis section is) does not add
that much value. The body text of the description where we refer to
the <branch> parameter of course need to be updated to say "in
addition, instead of a branch name, you can give a commit-ish that
is *not* a branch name. When you do so, instead of checking out the
branch, the HEAD is detached at that commit before the history
leading to it is rebased."
And because we have to say "it can be a non-branch commit-ish and
here is what happens when you do so" anyway, I think the current
synopsis as-is would be better than making it less clear and more
scary by replacing <branch> with other things like <commit-ish> or
[<branch> | <commit-ish>].
[Footnote]
*1* As my "log --first-parent --oneline master..pu" is a strand of
pearls each of which is a merge of a topic branch,
$ git rebase -i master pu~$n^2
can be a handy way to make a trial rebase (after double checking
the result of "git tbdiff", I may do "git checkout -B topic" to
overwrite the original or I may discard the result of rebasing).
next prev parent reply other threads:[~2017-11-29 0:10 UTC|newest]
Thread overview: 18+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-11-21 15:25 [PATCH] rebase: rebasing can also be done when HEAD is detached Kaartic Sivaraam
2017-11-22 2:13 ` Junio C Hamano
2017-11-27 17:21 ` [PATCH v2 0/3] rebase: give precise error message Kaartic Sivaraam
2017-11-27 17:21 ` [PATCH v2 1/3] rebase: use a more appropriate variable name Kaartic Sivaraam
2017-11-27 17:21 ` [PATCH v2 2/3] rebase: distinguish user input by quoting it Kaartic Sivaraam
2017-11-27 17:21 ` [PATCH v2 3/3] rebase: rebasing can also be done when HEAD is detached Kaartic Sivaraam
2017-11-28 2:31 ` Junio C Hamano
2017-11-28 16:15 ` Kaartic Sivaraam
2017-12-01 6:09 ` [PATCH v3 " Kaartic Sivaraam
2017-11-28 2:25 ` [PATCH v2 0/3] rebase: give precise error message Junio C Hamano
2017-11-28 14:04 ` Kaartic Sivaraam
2017-11-29 0:10 ` Junio C Hamano [this message]
2017-11-29 3:11 ` Kaartic Sivaraam
2017-11-29 6:47 ` Junio C Hamano
2017-12-16 9:03 ` [PATCH v5 0/3] rebase: give precise error messages Kaartic Sivaraam
2017-12-16 9:03 ` [PATCH v5 1/3] rebase: consistently use branch_name variable Kaartic Sivaraam
2017-12-16 9:03 ` [PATCH v5 2/3] rebase: distinguish user input by quoting it Kaartic Sivaraam
2017-12-16 9:03 ` [PATCH v5 3/3] rebase: rebasing can also be done when HEAD is detached Kaartic Sivaraam
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=xmqqzi7654hx.fsf@gitster.mtv.corp.google.com \
--to=gitster@pobox$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=kaartic.sivaraam@gmail$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox