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

From: Jonathan Nieder <jrnieder@gmail•com>
To: Junio C Hamano <gitster@pobox•com>
Cc: Benjamin Bergman <ben@benbergman•ca>, git@vger•kernel.org
Subject: Re: [PATCH] Documentation/git-checkout: Move `--detach` flag in synopsis to correct command
Date: Wed, 11 Sep 2013 12:06:41 -0700	[thread overview]
Message-ID: <20130911190641.GF4326@google.com> (raw)
In-Reply-To: <xmqq1u4vuw4y.fsf@gitster.dls.corp.google.com>

Hi,

Junio C Hamano wrote:

> --- a/Documentation/git-checkout.txt
> +++ b/Documentation/git-checkout.txt
> @@ -9,7 +9,8 @@ SYNOPSIS
>  --------
>  [verse]
>  'git checkout' [-q] [-f] [-m] [<branch>]
> -'git checkout' [-q] [-f] [-m] [--detach] [<commit>]
> +'git checkout' [-q] [-f] [-m] --detach [<branch>]
> +'git checkout' [-q] [-f] [-m] [--detach] <commit>
>  'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
>  'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
>  'git checkout' [-p|--patch] [<tree-ish>] [--] [<paths>...]
> @@ -62,7 +63,7 @@ that is to say, the branch is not reset/created unless "git checkout" is
>  successful.
>  
>  'git checkout' --detach [<branch>]::
> -'git checkout' <commit>::
> +'git checkout' [--detach] <commit>::

Looks sensible.

[...]
> @@ -71,10 +72,13 @@ successful.
>  	tree will be the state recorded in the commit plus the local
>  	modifications.
>  +
> -Passing `--detach` forces this behavior in the case of a <branch> (without
> -the option, giving a branch name to the command would check out the branch,
> -instead of detaching HEAD at it), or the current commit,
> -if no <branch> is specified.
> +Even though a branch name can be used to name a commit, you have to
> +explicitly say `git checkout --detach <branch>` when you want to
> +detach HEAD at the tip of the branch (`git checkout <branch>` will
> +check out that branch without detaching HEAD).  Omitting <branch>,
> +i.e. `git checkout --detach` detaches HEAD at the tip of the current
> +branch.  When naming the commit in a form other than just a branch
> +name, e.g. `master^0`, `HEAD~4`, `c2f3bf071e`, you can omit --detach.

Hm.  I agree that the old explanation is overly convoluted, but I don't
think the replacement is clear enough yet.  The "Even though a branch
name can be used to name a commit," part forced me to pause for too
long --- why is this telling me that a branch can be used to name a
commit, and in what context?

I think the main problem with the old text is that it tried to say too
much in one sentence.

The explanation lower down of the --detach option does this rather
well:

	--detach
		Rather than checking out a branch to work on it, check
		out a commit for inspection and discardable
		experiments.  This is the default behavior of
		"git checkout <commit>" when <commit> is not a branch
		name.  See the "DETACHED HEAD" section below for
		details.

How about splitting this into multiple paragraphs, like so?  In the
suggestion below I also cleaned up the language a little.

	git checkout --detach [<branch>], git checkout [--detach] <commit>
		Prepare to work on top of <commit>, by detaching [...]

		When the <commit> argument is a branch name, the --detach
		option can be used to detach HEAD at the tip of the
		branch ('git checkout <branch>' would check out that
		branch without detaching HEAD).

		Omitting <branch> detaches HEAD at the tip of the
		current branch.

I'd leave out the last sentence about commits other than branch names,
since it is already implied by the [--detach] in the syntax.

Thanks and hope that helps,
Jonathan

     prev parent reply	other threads:[~2013-09-11 19:06 UTC|newest]

Thread overview: 3+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2013-09-11  2:37 [PATCH] Documentation/git-checkout: Move `--detach` flag in synopsis to correct command Benjamin Bergman
2013-09-11 17:05 ` Junio C Hamano
2013-09-11 19:06   ` Jonathan Nieder [this message]

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=20130911190641.GF4326@google.com \
    --to=jrnieder@gmail$(echo .)com \
    --cc=ben@benbergman$(echo .)ca \
    --cc=git@vger$(echo .)kernel.org \
    --cc=gitster@pobox$(echo .)com \
    /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