Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage
Chris Rorvick writes: > I like Johannes' suggestion of using "" in the --detach case > instead of "" as I think it makes the reason for the > separation more obvious at a glance. Sounds sensible; even though the option does not require its argument to be a branch name, the user does not have a reason to use the option if it is not giving a branch name, either, so it all balances out ;-). > > --->8--- > diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt > index dcf1a32..4fdf41a 100644 > --- a/Documentation/git-checkout.txt > +++ b/Documentation/git-checkout.txt > @@ -61,8 +61,8 @@ $ git checkout > that is to say, the branch is not reset/created unless "git checkout" is > successful. > > -'git checkout' --detach []:: > 'git checkout' :: > +'git checkout' --detach []:: > > Prepare to work on top of , by detaching HEAD at it > (see "DETACHED HEAD" section), and updating the index and the > @@ -71,7 +71,8 @@ successful. > tree will be the state recorded in the commit plus the local > modifications. > + > -Passing `--detach` forces this behavior even if is a branch. > +Passing `--detach` forces this behavior in the case of a , or > +the current branch if one is not specified. > > 'git checkout' [-p|--patch] [] [--] ...:: -- 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: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage
On Mon, Dec 17, 2012 at 7:53 PM, Junio C Hamano wrote: > Here is a work-in-progress relative to Chris's 83c9989 > (Documentation/git-checkout.txt: document 70c9ac2 behavior, > 2012-12-17). It sounds pretty good to me. > @@ -54,12 +61,17 @@ $ git checkout > that is to say, the branch is not reset/created unless "git checkout" is > successful. > > -'git checkout' [--detach] []:: > +'git checkout' --detach []:: > +'git checkout' :: > > - Update the index and working tree to reflect the specified > - commit and set HEAD to point directly to (see > - "DETACHED HEAD" section.) Passing `--detach` forces this > - behavior even if is a branch. > + Prepare to work on top of , by detaching HEAD at it > + (see "DETACHED HEAD" section), and updating the index and the > + files in the working tree. Local modifications to the files > + in the working tree are kept, so that the resulting working > + tree will be the state recorded in the commit plus the local > + modifications. > ++ > +Passing `--detach` forces this behavior even if is a branch. > > 'git checkout' [-p|--patch] [] [--] ...:: > I like Johannes' suggestion of using "" in the --detach case instead of "" as I think it makes the reason for the separation more obvious at a glance. On top of your changes, maybe something like: --->8--- diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index dcf1a32..4fdf41a 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -61,8 +61,8 @@ $ git checkout that is to say, the branch is not reset/created unless "git checkout" is successful. -'git checkout' --detach []:: 'git checkout' :: +'git checkout' --detach []:: Prepare to work on top of , by detaching HEAD at it (see "DETACHED HEAD" section), and updating the index and the @@ -71,7 +71,8 @@ successful. tree will be the state recorded in the commit plus the local modifications. + -Passing `--detach` forces this behavior even if is a branch. +Passing `--detach` forces this behavior in the case of a , or +the current branch if one is not specified. 'git checkout' [-p|--patch] [] [--] ...:: -- 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: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage
On Mon, Dec 17, 2012 at 2:20 AM, Johannes Sixt wrote: >>> +'git checkout' [--detach] []:: > > The title here is better spelled as two lines: > > 'git checkout' :: > 'git checkout' --detach :: AsciiDoc renders these horizontally separated by a comma when formatted as a man page instead of vertically as written (and as rendered by the HTML documentation.) I think this makes this separation into two less effective, but at least it doesn't line wrap on an 80-wide terminal like the previous title did. Chris -- 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: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage
I like these, and I think they are conveying the right amount of
information. There is a slight discrepancy between the and
versions, where it seems we are assuming that by checking out
a commit you are intending to work 'on top of' it. This could be
avoided by using the term 'with' in both cases. Also, they are in
different tenses, but I'm not sure which is preferred ('Prepare to' vs
'To prepare for').
In the second tense, these opening lines might look like this:
+ To prepare for working with , switch to it by updating
+ To prepare for working with , detach HEAD at it
+ (see "DETACHED HEAD" section), and update the index and the
+ files in the working tree.
Regards,
Andrew Ardill
--
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: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage
Junio C Hamano writes: > I agree with you that sightseeing use case where you do not intend > to make any commit is also important. That is exactly why I said > "further work is done on that branch" not "to that branch" in the > message you are responding to. Here is a work-in-progress relative to Chris's 83c9989 (Documentation/git-checkout.txt: document 70c9ac2 behavior, 2012-12-17). Even though "switch to that specific branch" may be easy to grasp as a concept, I do not think "switch to detached HEAD" makes much sense, so I ended up with "switch" for the case, and "detach" for the "--detach" one, at least for now. diff --git c/Documentation/git-checkout.txt w/Documentation/git-checkout.txt index db89cf7..dcf1a32 100644 --- c/Documentation/git-checkout.txt +++ w/Documentation/git-checkout.txt @@ -21,10 +21,12 @@ or the specified tree. If no paths are given, 'git checkout' will also update `HEAD` to set the specified branch as the current branch. -'git checkout' []:: - - Update the index, working tree, and HEAD to reflect the - specified branch. +'git checkout' :: + To prepare for working on , switch to it by updating + the index and the files in the working tree, and by pointing + HEAD at the branch. Local modifications to the files in the + working tree are kept, so that they can be committed to the + . + If is not found but there does exist a tracking branch in exactly one remote (call it ) with a matching name, treat as @@ -33,6 +35,11 @@ equivalent to $ git checkout -b --track / ++ +You could omit , in which case the command degenerates to +"check out the current branch", which is a glorified no-op with a +rather expensive side-effects to show only the tracking information, +if exists, for the current branch. 'git checkout' -b|-B []:: @@ -54,12 +61,17 @@ $ git checkout that is to say, the branch is not reset/created unless "git checkout" is successful. -'git checkout' [--detach] []:: +'git checkout' --detach []:: +'git checkout' :: - Update the index and working tree to reflect the specified - commit and set HEAD to point directly to (see - "DETACHED HEAD" section.) Passing `--detach` forces this - behavior even if is a branch. + Prepare to work on top of , by detaching HEAD at it + (see "DETACHED HEAD" section), and updating the index and the + files in the working tree. Local modifications to the files + in the working tree are kept, so that the resulting working + tree will be the state recorded in the commit plus the local + modifications. ++ +Passing `--detach` forces this behavior even if is a branch. 'git checkout' [-p|--patch] [] [--] ...:: -- 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: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage
On 18 December 2012 08:59, Junio C Hamano wrote: > Andrew Ardill writes: >> Even if the primary purpose of "git checkout " is to "check >> out the branch so that further work is done on that branch", I don't >> believe that means it has to be stated first. In fact, I would say >> that there are enough other use cases that the language should be >> slightly more use-case agnostic in the first situation. For example, >> someone might switch to another branch or commit simply to see what >> state the tree was in at that point. > > I've been deliberately avoiding the term "switch", actually. I > agree that it may be familiar to people with prior exposure to > subversion, but that is not the primary audience of the manual. I don't have much experience with svn, so I didn't make that connection. Independent of svn usage, what is wrong with the term 'switch'? I would be interested to hear how translators communicate the checkout concept, as I assume the word checkout doesn't exist in many languages. For me, switching between revisions is a natural way of phrasing the action, but perhaps there is a better way of saying the same thing? >> Some people use checkout to >> deploy a tag of the working tree onto a production server. The first >> example in particular is, I think, a common enough operation that >> restricting the opening lines of documentation to talking about >> building further work is misleading. > > I agree with you that sightseeing use case where you do not intend > to make any commit is also important. That is exactly why I said > "further work is done on that branch" not "to that branch" in the > message you are responding to. Ah ok, I didn't pick up on that nuance. Your suggestion from earlier has, for example, "Prepare to work on building new history on " which *is* excluding that use case. Perhaps modifying similar lines to something like "Prepare to work with the repository/history/something from " or maybe just "Prepare to work with " would better encapsulate those use cases. Following lines would expand on what it means to work with a branch or commit, and the technical details of updates to the repositories current state. Regards, Andrew Ardill -- 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: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage
From: "Junio C Hamano" Sent: Monday, December 17, 2012 9:13 PM "Philip Oakley" writes: From: "Junio C Hamano" Sent: Monday, December 17, This is to "check out the branch" ;-) ... From a user perspective it's better to refer to the working directory first rather than the internal mechanics. Prepare to work on , by updating the files in the working tree and index to the branch's previous content, and pointing HEAD to it. I agree that the mention of "pointing HEAD to" may be better to be rephrased in the user facing terms. Because the primary purpose of "git checkout " is to "check out the branch so that further work is done on that branch", that aspect of the behaviour should be mentioned first. That part is OK, but it is a bit tautological. Updating of the working tree files and the index is the implemenation detail of starting to work on that branch. It was this part that I felt needed the worker's work-tree mentioned first. It could be argued that workers think they do work on the tree, and that the branch name is an administrative place holder. When the two sentences are back to back it was OK, as you had still included the key element of my suggestion. So your suggestion is going backwards, I'd have to say. A misunderstanding of the suggestion perhaps? Philip -- 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: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage
Andrew Ardill writes: > Even if the primary purpose of "git checkout " is to "check > out the branch so that further work is done on that branch", I don't > believe that means it has to be stated first. In fact, I would say > that there are enough other use cases that the language should be > slightly more use-case agnostic in the first situation. For example, > someone might switch to another branch or commit simply to see what > state the tree was in at that point. I've been deliberately avoiding the term "switch", actually. I agree that it may be familiar to people with prior exposure to subversion, but that is not the primary audience of the manual. > Some people use checkout to > deploy a tag of the working tree onto a production server. The first > example in particular is, I think, a common enough operation that > restricting the opening lines of documentation to talking about > building further work is misleading. I agree with you that sightseeing use case where you do not intend to make any commit is also important. That is exactly why I said "further work is done on that branch" not "to that branch" in the message you are responding to. -- 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: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage
On 18 December 2012 08:13, Junio C Hamano wrote: > "Philip Oakley" writes: > >> From: "Junio C Hamano" Sent: Monday, December 17, >>> This is to "check out the branch" ;-) >>> ... >> >> From a user perspective it's better to refer to the working directory >> first rather than the internal mechanics. >> >>Prepare to work on , by updating the files in the >>working tree and index to the branch's previous content, and >>pointing HEAD to it. > > I agree that the mention of "pointing HEAD to" may be better to be > rephrased in the user facing terms. > > Because the primary purpose of "git checkout " is to "check > out the branch so that further work is done on that branch", that > aspect of the behaviour should be mentioned first. Updating of the > working tree files and the index is the implemenation detail of > starting to work on that branch. Even if the primary purpose of "git checkout " is to "check out the branch so that further work is done on that branch", I don't believe that means it has to be stated first. In fact, I would say that there are enough other use cases that the language should be slightly more use-case agnostic in the first situation. For example, someone might switch to another branch or commit simply to see what state the tree was in at that point. Some people use checkout to deploy a tag of the working tree onto a production server. The first example in particular is, I think, a common enough operation that restricting the opening lines of documentation to talking about building further work is misleading. My earlier submission dealt with this by using the 'Switch to the specified ...' terminology. For me this is implicitly stating 'Switch the state of the repository to be the same as the specified ...' but perhaps it would do to be more explicit? I prefer the shorter form myself. By following this with the typical use case it makes it clear what the intended use of the command is, and some idea about the mechanics of its function. I realised that my signature was improperly placed when I submitted my suggestion last, so I will include it here as reference for anyone who skipped over it. It builds on top of the two original patches. Regards, Andrew Ardill -->8-- From: Andrew Ardill Date: Mon, 17 Dec 2012 18:53:41 +1100 Subject: [PATCH] Documentation/git-checkout.txt: Use consistent terminology git checkout is described as 'switching' branches in places. Use this terminology more consistently. Expand on the purpose of switching to a branch or commit, which is typically to prepare to build history on top of that branch or commit. Signed-off-by: Andrew Ardill --- Documentation/git-checkout.txt | 18 -- 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index db89cf7..e6db14f 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -23,8 +23,11 @@ branch. 'git checkout' []:: - Update the index, working tree, and HEAD to reflect the - specified branch. + Switch to the specified . Prepares for building new + history on , by updating the index and the files in the + working tree, and by pointing HEAD at the branch. Local + modifications to the files in the working tree are kept, so that + they can be committed on the . + If is not found but there does exist a tracking branch in exactly one remote (call it ) with a matching name, treat as @@ -56,10 +59,13 @@ successful. 'git checkout' [--detach] []:: - Update the index and working tree to reflect the specified - commit and set HEAD to point directly to (see - "DETACHED HEAD" section.) Passing `--detach` forces this - behavior even if is a branch. + Switch to the specified . Prepares for building new + history on top of , by updating the index and the files + in the working tree, and by pointing HEAD at . Local + modifications to the files in the working tree are kept, so that + they can be committed on top of . Passing `--detach` + forces HEAD to point directly at even if is a + branch (see "DETACHED HEAD" section.) 'git checkout' [-p|--patch] [] [--] ...:: -- -- 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: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage
"Philip Oakley" writes: > From: "Junio C Hamano" Sent: Monday, December 17, >> This is to "check out the branch" ;-) >> ... > > From a user perspective it's better to refer to the working directory > first rather than the internal mechanics. > >Prepare to work on , by updating the files in the >working tree and index to the branch's previous content, and >pointing HEAD to it. I agree that the mention of "pointing HEAD to" may be better to be rephrased in the user facing terms. Because the primary purpose of "git checkout " is to "check out the branch so that further work is done on that branch", that aspect of the behaviour should be mentioned first. Updating of the working tree files and the index is the implemenation detail of starting to work on that branch. So your suggestion is going backwards, I'd have to say. -- 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: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage
From: "Junio C Hamano" Sent: Monday, December 17, 2012 7:21 AM Chris Rorvick writes: The forms of checkout that do not take a path are lumped together in the DESCRIPTION section, but the description for this group is dominated by explanation of the -b|-B form. Split these apart for more clarity. Signed-off-by: Chris Rorvick --- Documentation/git-checkout.txt | 26 +- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 7958a47..a47555c 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -22,17 +22,18 @@ also update `HEAD` to set the specified branch as the current branch. 'git checkout' []:: + + Update the index, working tree, and HEAD to reflect the + specified branch. This is to "check out the branch" ;-) But of course, we cannot define "checkout" in terms of "checkout", so we need to phrase it without saying "checkout" and explain what it *means* to check out the branch. I am not sure "Reflect" is a good word. Making the result similar to the branch is only one aspect of the act of checking out the branch. The other equally important aspect is that this is done to advance the history of the branch. Perhaps... Prepare to work on building new history on , by pointing the HEAD to the branch and updating the index and the files in the working tree. Local modifications to the files in the working tree are kept, so that they can be committed on the . From a user perspective it's better to refer to the working directory first rather than the internal mechanics. Perhaps: Prepare to work on , by updating the files in the working tree and index to the branch's previous content, and pointing HEAD to it. Local modifications to the files in the working tree are kept, so that they can be committed on the . 'git checkout' -b|-B []:: + Specifying `-b` causes a new branch to be created as if + linkgit:git-branch[1] were called and then checked out. In + this case you can use the `--track` or `--no-track` options, + which will be passed to 'git branch'. As a convenience, + `--track` without `-b` implies branch creation; see the + description of `--track` below. + If `-B` is given, is created if it doesn't exist; otherwise, it is reset. This is the transactional equivalent of @@ -45,6 +46,13 @@ $ git checkout that is to say, the branch is not reset/created unless "git checkout" is successful. +'git checkout' [--detach] []:: + + Update the index and working tree to reflect the specified + commit and set HEAD to point directly to (see + "DETACHED HEAD" section.) Passing `--detach` forces this + behavior even if is a branch. Prepare to work on building new history on top of , by detaching HEAD at the commit and ...(likewise)... -- 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: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage
Johannes Sixt writes: > Am 12/17/2012 9:48, schrieb Junio C Hamano: >> Here is what I tentatively have ... > > Thanks! > >> -'git checkout' [--detach] []:: >> +'git checkout' --detach []:: >> +'git checkout' :: >> >> -Update the index and working tree to reflect the specified >> -commit and set HEAD to point directly to (see >> -"DETACHED HEAD" section.) Passing `--detach` forces this >> -behavior even if is a branch. >> +Prepare to work on building new history on top of , >> +by detaching HEAD at the commit (see "DETACHED HEAD" >> +section), and updating the index and the files in the >> +working tree. Local modifications to the files in the >> +working tree are kept, so that they can be committed on the >> +. > > The last half-sentence should better be removed. True; we do not have a particular "on the " in this state. At least, "on the " needs to be removed. But I think we may want a more different wording here, including the earlier "work on building new history on top of" part. The detached HEAD state primarily is a sightseeing mode, where the user is expected to view but not touch. Even for experienced users, commits on a detached HEAD are for keeping snapshots of interim states during a throw-away experiment, so the purpose of detaching is not exactly "to work on *building* new history" in the first place. Carefree experimentation is encouraged by not forbidding commmits from this state, with the expectation that: (1) if it does not lead to interesting result, another "git checkout " will wipe the throw-away experiment without affecting any of your more important branches; and (2) an experiment that yielded something useful can be further polished on a concrete branch by "git checkout -b ". I think the above discussion on detached HEAD can be added to its own section. Prepare to work on top of , by detaching HEAD at it (see "DETACHED HEAD" section), and updating te index and the files in the working tree. Local modifications to the files in the working tree are kept, so that the resulting working tree will be the state recorded in the commit plus the local modifications. Or something, perhaps? -- 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: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage
Am 12/17/2012 9:48, schrieb Junio C Hamano: > Here is what I tentatively have ... Thanks! > -'git checkout' [--detach] []:: > +'git checkout' --detach []:: > +'git checkout' :: > > - Update the index and working tree to reflect the specified > - commit and set HEAD to point directly to (see > - "DETACHED HEAD" section.) Passing `--detach` forces this > - behavior even if is a branch. > + Prepare to work on building new history on top of , > + by detaching HEAD at the commit (see "DETACHED HEAD" > + section), and updating the index and the files in the > + working tree. Local modifications to the files in the > + working tree are kept, so that they can be committed on the > + . The last half-sentence should better be removed. > ++ > +Passing `--detach` forces this behavior even if is a branch. > > 'git checkout' [-p|--patch] [] [--] ...:: -- Hannes -- 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: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage
Regards, Andrew Ardill On 17 December 2012 19:20, Johannes Sixt wrote: > Am 12/17/2012 8:21, schrieb Junio C Hamano: >> Chris Rorvick writes: >>> 'git checkout' []:: > > Is really optional in this form? > > BTW, what does plain 'git checkout' do? Just report ahead/behind information? I think it defaults to either HEAD or the current branch, which shows uncommitted changes and relationship to upstream. >>> + >>> +Update the index, working tree, and HEAD to reflect the >>> +specified branch. > ... >>> +'git checkout' [--detach] []:: > > The title here is better spelled as two lines: > > 'git checkout' :: > 'git checkout' --detach :: > > I don't think that or should be indicated as optional here. doing 'git checkout --detach' will detach from the current branch if you have one, but maybe listing as optional would work in that case? Here is my suggestion, differing from what Junio put forward primarily by first indicating that a checkout is a 'switch' to a different branch or commit. This makes sense to me, and is used elsewhere in the documentation, so I thought it might make sense here too. -->8-- From: Andrew Ardill Date: Mon, 17 Dec 2012 18:53:41 +1100 Subject: [PATCH] Documentation/git-checkout.txt: Use consistent terminology git checkout is described as 'switching' branches in places. Use this terminology more consistently. Expand on the purpose of switching to a branch or commit, which is typically to prepare to build history on top of that branch or commit. Signed-off-by: Andrew Ardill --- Documentation/git-checkout.txt | 18 -- 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index db89cf7..e6db14f 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -23,8 +23,11 @@ branch. 'git checkout' []:: - Update the index, working tree, and HEAD to reflect the - specified branch. + Switch to the specified . Prepares for building new + history on , by updating the index and the files in the + working tree, and by pointing HEAD at the branch. Local + modifications to the files in the working tree are kept, so that + they can be committed on the . + If is not found but there does exist a tracking branch in exactly one remote (call it ) with a matching name, treat as @@ -56,10 +59,13 @@ successful. 'git checkout' [--detach] []:: - Update the index and working tree to reflect the specified - commit and set HEAD to point directly to (see - "DETACHED HEAD" section.) Passing `--detach` forces this - behavior even if is a branch. + Switch to the specified . Prepares for building new + history on top of , by updating the index and the files + in the working tree, and by pointing HEAD at . Local + modifications to the files in the working tree are kept, so that + they can be committed on top of . Passing `--detach` + forces HEAD to point directly at even if is a + branch (see "DETACHED HEAD" section.) 'git checkout' [-p|--patch] [] [--] ...:: -- -- 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: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage
Here is what I tentatively have (so that I do not forget) on 'pu', marked with "(squash???)", as a suggested update on top of Chris's patches. Documentation/git-checkout.txt | 29 + 1 file changed, 21 insertions(+), 8 deletions(-) diff --git c/Documentation/git-checkout.txt w/Documentation/git-checkout.txt index db89cf7..0e50eeb 100644 --- c/Documentation/git-checkout.txt +++ w/Documentation/git-checkout.txt @@ -21,10 +21,13 @@ or the specified tree. If no paths are given, 'git checkout' will also update `HEAD` to set the specified branch as the current branch. -'git checkout' []:: +'git checkout' :: - Update the index, working tree, and HEAD to reflect the - specified branch. + Prepare to work on building new history on , by + pointing the HEAD to the branch and updating the index and + the files in the working tree. Local modifications to the + files in the working tree are kept, so that they can be + committed on the . + If is not found but there does exist a tracking branch in exactly one remote (call it ) with a matching name, treat as @@ -33,6 +36,11 @@ equivalent to $ git checkout -b --track / ++ +You could omit , in which case the command degenerates to +"check out the current branch", which is a glorified no-op with a +rather expensive side-effects to show only the tracking information, +if exists, for the current branch. 'git checkout' -b|-B []:: @@ -54,12 +62,17 @@ $ git checkout that is to say, the branch is not reset/created unless "git checkout" is successful. -'git checkout' [--detach] []:: +'git checkout' --detach []:: +'git checkout' :: - Update the index and working tree to reflect the specified - commit and set HEAD to point directly to (see - "DETACHED HEAD" section.) Passing `--detach` forces this - behavior even if is a branch. + Prepare to work on building new history on top of , + by detaching HEAD at the commit (see "DETACHED HEAD" + section), and updating the index and the files in the + working tree. Local modifications to the files in the + working tree are kept, so that they can be committed on the + . ++ +Passing `--detach` forces this behavior even if is a branch. 'git checkout' [-p|--patch] [] [--] ...:: -- 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: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage
Am 12/17/2012 8:21, schrieb Junio C Hamano: > Chris Rorvick writes: >> 'git checkout' []:: Is really optional in this form? BTW, what does plain 'git checkout' do? Just report ahead/behind information? >> + >> +Update the index, working tree, and HEAD to reflect the >> +specified branch. ... >> +'git checkout' [--detach] []:: The title here is better spelled as two lines: 'git checkout' :: 'git checkout' --detach :: I don't think that or should be indicated as optional here. >> + >> +Update the index and working tree to reflect the specified >> +commit and set HEAD to point directly to (see >> +"DETACHED HEAD" section.) Passing `--detach` forces this >> +behavior even if is a branch. > > Prepare to work on building new history on top of , > by detaching HEAD at the commit and ...(likewise)... -- Hannes -- 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: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage
Chris Rorvick writes: > The forms of checkout that do not take a path are lumped together in the > DESCRIPTION section, but the description for this group is dominated by > explanation of the -b|-B form. Split these apart for more clarity. > > Signed-off-by: Chris Rorvick > --- > Documentation/git-checkout.txt | 26 +- > 1 file changed, 17 insertions(+), 9 deletions(-) > > diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt > index 7958a47..a47555c 100644 > --- a/Documentation/git-checkout.txt > +++ b/Documentation/git-checkout.txt > @@ -22,17 +22,18 @@ also update `HEAD` to set the specified branch as the > current > branch. > > 'git checkout' []:: > + > + Update the index, working tree, and HEAD to reflect the > + specified branch. This is to "check out the branch" ;-) But of course, we cannot define "checkout" in terms of "checkout", so we need to phrase it without saying "checkout" and explain what it *means* to check out the branch. I am not sure "Reflect" is a good word. Making the result similar to the branch is only one aspect of the act of checking out the branch. The other equally important aspect is that this is done to advance the history of the branch. Perhaps... Prepare to work on building new history on , by pointing the HEAD to the branch and updating the index and the files in the working tree. Local modifications to the files in the working tree are kept, so that they can be committed on the . > 'git checkout' -b|-B []:: > > + Specifying `-b` causes a new branch to be created as if > + linkgit:git-branch[1] were called and then checked out. In > + this case you can use the `--track` or `--no-track` options, > + which will be passed to 'git branch'. As a convenience, > + `--track` without `-b` implies branch creation; see the > + description of `--track` below. > + > If `-B` is given, is created if it doesn't exist; otherwise, it > is reset. This is the transactional equivalent of > @@ -45,6 +46,13 @@ $ git checkout > that is to say, the branch is not reset/created unless "git checkout" is > successful. > > +'git checkout' [--detach] []:: > + > + Update the index and working tree to reflect the specified > + commit and set HEAD to point directly to (see > + "DETACHED HEAD" section.) Passing `--detach` forces this > + behavior even if is a branch. Prepare to work on building new history on top of , by detaching HEAD at the commit and ...(likewise)... -- 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
[PATCH 1/2] Documentation/git-checkout.txt: clarify usage
The forms of checkout that do not take a path are lumped together in the DESCRIPTION section, but the description for this group is dominated by explanation of the -b|-B form. Split these apart for more clarity. Signed-off-by: Chris Rorvick --- Documentation/git-checkout.txt | 26 +- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 7958a47..a47555c 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -22,17 +22,18 @@ also update `HEAD` to set the specified branch as the current branch. 'git checkout' []:: + + Update the index, working tree, and HEAD to reflect the + specified branch. + 'git checkout' -b|-B []:: -'git checkout' [--detach] []:: - This form switches branches by updating the index, working - tree, and HEAD to reflect the specified branch or commit. -+ -If `-b` is given, a new branch is created as if linkgit:git-branch[1] -were called and then checked out; in this case you can -use the `--track` or `--no-track` options, which will be passed to -'git branch'. As a convenience, `--track` without `-b` implies branch -creation; see the description of `--track` below. + Specifying `-b` causes a new branch to be created as if + linkgit:git-branch[1] were called and then checked out. In + this case you can use the `--track` or `--no-track` options, + which will be passed to 'git branch'. As a convenience, + `--track` without `-b` implies branch creation; see the + description of `--track` below. + If `-B` is given, is created if it doesn't exist; otherwise, it is reset. This is the transactional equivalent of @@ -45,6 +46,13 @@ $ git checkout that is to say, the branch is not reset/created unless "git checkout" is successful. +'git checkout' [--detach] []:: + + Update the index and working tree to reflect the specified + commit and set HEAD to point directly to (see + "DETACHED HEAD" section.) Passing `--detach` forces this + behavior even if is a branch. + 'git checkout' [-p|--patch] [] [--] ...:: When or `--patch` are given, 'git checkout' does *not* -- 1.8.1.rc1.203.g1ddc124 -- 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
