7 messages, 2 authors, 2016-06-15 · open the first message on its own page
From: Junio C Hamano <hidden>
Date: 2016-06-15 22:46:35
Jeff King [off-list ref] writes:
I think it would be better in the synopsis to split this into two use cases: git checkout [<branch>] git checkout -b <new_branch> [<start_point>] And then explain them as separate definitions.
I'd agree it would make it much nicer. Thanks for a bit of sanity. I sometimes misplace it when I got grumpy.
From: Jeff King <hidden>
Date: 2016-06-15 22:46:36
On Mon, Apr 13, 2009 at 02:54:27AM -0700, Junio C Hamano wrote:
quoted
I think it would be better in the synopsis to split this into two use cases: git checkout [<branch>] git checkout -b <new_branch> [<start_point>] And then explain them as separate definitions.I'd agree it would make it much nicer.
A 5-patch series follows which does this and a few other fixups. I think the result is better. 1/5 doc: clarify --no-track option 2/5 doc: refer to tracking configuration as "upstream" 3/5 doc/checkout: refer to git-branch(1) as appropriate 4/5 doc/checkout: split checkout and branch creation in synopsis 5/5 docs/checkout: clarify what "non-branch" means -Peff
From: Jeff King <hidden>
Date: 2016-06-15 22:46:36
It is not really about ignoring the config option; it is about turning off tracking, _even if_ the config option is set. Signed-off-by: Jeff King <redacted> --- This I just noticed while working in the area, and it bothered me. Documentation/git-branch.txt | 3 ++- Documentation/git-checkout.txt | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index ba3dea6..19f1b0d 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt@@ -124,7 +124,8 @@ OPTIONS start-point is either a local or remote branch. --no-track:: - Ignore the branch.autosetupmerge configuration variable. + Do not set up tracking configuration, even if the + branch.autosetupmerge configuration variable is true. --contains <commit>:: Only list branches which contain the specified commit.
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 223ea9c..4992fc6 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt@@ -90,7 +90,8 @@ guessing results in an empty name, the guessing is aborted. You can explicitly give a name with '-b' in such a case. --no-track:: - Ignore the branch.autosetupmerge configuration variable. + Do not set up tracking configuration, even if the + branch.autosetupmerge configuration variable is true. -l:: Create the new branch's reflog. This activates recording of
--
1.6.3.rc0.148.g141203.dirty
From: Jeff King <hidden>
Date: 2016-06-15 22:46:36
The term "tracking" often creates confusion between remote tracking branches and local branches which track a remote branch. The term "upstream" captures more clearly the idea of "branch A is based on branch B in some way", so it makes sense to mention it. At the same time, upstream branches are used for more than just git-pull these days; let's mention that here. Signed-off-by: Jeff King <redacted> --- I think this matches nicely with Santi's recent addition of upstream to the glossary. Documentation/git-branch.txt | 24 +++++++++++++----------- Documentation/git-checkout.txt | 2 +- 2 files changed, 14 insertions(+), 12 deletions(-)
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 19f1b0d..cbd4275 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt@@ -112,19 +112,21 @@ OPTIONS Display the full sha1s in the output listing rather than abbreviating them. --track:: - When creating a new branch, set up the configuration so that 'git-pull' - will automatically retrieve data from the start point, which must be - a branch. Use this if you always pull from the same upstream branch - into the new branch, and if you do not want to use "git pull - <repository> <refspec>" explicitly. This behavior is the default - when the start point is a remote branch. Set the - branch.autosetupmerge configuration variable to `false` if you want - 'git-checkout' and 'git-branch' to always behave as if '--no-track' were - given. Set it to `always` if you want this behavior when the - start-point is either a local or remote branch. + When creating a new branch, set up configuration to mark the + start-point branch as "upstream" from the new branch. This + configuration will tell git to show the relationship between the + two branches in `git status` and `git branch -v`. Furthermore, + it directs `git pull` without arguments to pull from the + upstream when the new branch is checked out. ++ +This behavior is the default when the start point is a remote branch. +Set the branch.autosetupmerge configuration variable to `false` if you +want `git checkout` and `git branch` to always behave as if '--no-track' +were given. Set it to `always` if you want this behavior when the +start-point is either a local or remote branch. --no-track:: - Do not set up tracking configuration, even if the + Do not set up "upstream" configuration, even if the branch.autosetupmerge configuration variable is true. --contains <commit>::
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 4992fc6..16d3c87 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt@@ -90,7 +90,7 @@ guessing results in an empty name, the guessing is aborted. You can explicitly give a name with '-b' in such a case. --no-track:: - Do not set up tracking configuration, even if the + Do not set up "upstream" configuration, even if the branch.autosetupmerge configuration variable is true. -l::
--
1.6.3.rc0.148.g141203.dirty
From: Jeff King <hidden>
Date: 2016-06-15 22:46:36
Most of description for the branch creation options is
simply cut and paste from git-branch. There are two reasons
to fix this:
1. It can grow stale with respect to what's in "git
branch" (which it is now is).
2. It is not just an implementation detail, but rather the
desired mental model for the command that we are using
"git branch" here. Being explicit about that can help
the user understand what is going on.
It also makes sense to strip the branch creation options
from the synopsis, as they are making it a long,
hard-to-read line. They are still easily discovered by
reading the options list, and --track is explicitly
referenced when branch creation is described.
Signed-off-by: Jeff King <redacted>
---
There are two things here that people might disagree with:
1. Referring the user instead of using asciidoc magic to just include
the repeated text. While it is nice to save the user the effort
of referencing the other documentation, I think sometimes we go too
far with this in git. Sometimes it is beneficial for the user not
just to get the information, but to have it pointed out that the
link exists. Then they can better understand exactly what it is git
is doing (it is not "oh, this is a totally unrelated way to create
branches" but "this is a convenience wrapper that calls git branch"
-- I think the latter is the model we want to use).
2. Shortening the synopsis field. The long lines look awful in the
manpage on an 80-column terminal. I don't read git documentation
very often, so I have not really noticed, but some of our synopses
are quite complex and IMHO unreadable. We are much better off just
saying "there are some options, then these 1 or 2 arguments" which
give an overview of how you would invoke the command. You can look
at the option list if you want to actually see the options.
In this patch I just shortened the ones related to branch creation.
But I was tempted to take this a step further and get rid of the
"-f", "-q", and "-m" options in the synopsis, as well, which I think
would look much better.
Documentation/git-checkout.txt | 28 +++++++++-------------------
1 files changed, 9 insertions(+), 19 deletions(-)
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 16d3c87..22ad10d 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt@@ -8,7 +8,7 @@ git-checkout - Checkout a branch or paths to the working tree SYNOPSIS -------- [verse] -'git checkout' [-q] [-f] [-t | --track | --no-track] [-b <new_branch> [-l]] [-m] [<branch>] +'git checkout' [-q] [-f] [-m] [-b <new_branch>] [<branch>] 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>... DESCRIPTION
@@ -18,8 +18,9 @@ When <paths> are not given, this command switches branches by updating the index and working tree to reflect the specified branch, <branch>, and updating HEAD to be <branch> or, if specified, <new_branch>. Using -b will cause <new_branch> to -be created; in this case you can use the --track or --no-track -options, which will be passed to `git branch`. +be created as if linkgit:git-branch[1] were called; in this case you can +use the --track or --no-track options, which will be passed to `git +branch`. As a convenience, --track will default to creating a branch whose name is constructed from the specified branch name by stripping
@@ -62,22 +63,12 @@ entries; instead, unmerged entries are ignored. -b:: Create a new branch named <new_branch> and start it at - <branch>. The new branch name must pass all checks defined - by linkgit:git-check-ref-format[1]. Some of these checks - may restrict the characters allowed in a branch name. + <branch>; see linkgit:git-branch[1] for details. -t:: --track:: - When creating a new branch, set up configuration so that 'git-pull' - will automatically retrieve data from the start point, which must be - a branch. Use this if you always pull from the same upstream branch - into the new branch, and if you don't want to use "git pull - <repository> <refspec>" explicitly. This behavior is the default - when the start point is a remote branch. Set the - branch.autosetupmerge configuration variable to `false` if you want - 'git checkout' and 'git branch' to always behave as if '--no-track' were - given. Set it to `always` if you want this behavior when the - start point is either a local or remote branch. + When creating a new branch, set up "upstream" configuration. See + "--track" in linkgit:git-branch[1] for details. + If no '-b' option is given, the name of the new branch will be derived from the remote branch. If "remotes/" or "refs/remotes/"
@@ -94,9 +85,8 @@ explicitly give a name with '-b' in such a case. branch.autosetupmerge configuration variable is true. -l:: - Create the new branch's reflog. This activates recording of - all changes made to the branch ref, enabling use of date - based sha1 expressions such as "<branchname>@\{yesterday}". + Create the new branch's reflog; see linkgit:git-branch[1] for + details. -m:: --merge::
--
1.6.3.rc0.148.g141203.dirty
From: Jeff King <hidden>
Date: 2016-06-15 22:46:36
These can really be thought of as two different modes, since the "<branch>" parameter is treated differently in the two (in one it is the branch to be checked out, but in the other it is really a start-point for branch creation). Signed-off-by: Jeff King <redacted> --- This was the actual goal of the series. :) Documentation/git-checkout.txt | 40 ++++++++++++++++++++++------------------ 1 files changed, 22 insertions(+), 18 deletions(-)
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 22ad10d..4a1fb53 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt@@ -8,23 +8,22 @@ git-checkout - Checkout a branch or paths to the working tree SYNOPSIS -------- [verse] -'git checkout' [-q] [-f] [-m] [-b <new_branch>] [<branch>] +'git checkout' [-q] [-f] [-m] [<branch>] +'git checkout' [-q] [-f] [-m] [-b <new_branch>] [<start_point>] 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>... DESCRIPTION ----------- When <paths> are not given, this command switches branches by -updating the index and working tree to reflect the specified -branch, <branch>, and updating HEAD to be <branch> or, if -specified, <new_branch>. Using -b will cause <new_branch> to -be created as if linkgit:git-branch[1] were called; in this case you can -use the --track or --no-track options, which will be passed to `git -branch`. +updating the index, working tree, and HEAD to reflect the specified +branch. -As a convenience, --track will default to creating a branch whose -name is constructed from the specified branch name by stripping -the first namespace level. +If `-b` is given, a new branch is created and checked out, as if +linkgit:git-branch[1] were called; 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. When <paths> are given, this command does *not* switch branches. It updates the named paths in the working tree from
@@ -63,7 +62,7 @@ entries; instead, unmerged entries are ignored. -b:: Create a new branch named <new_branch> and start it at - <branch>; see linkgit:git-branch[1] for details. + <start_point>; see linkgit:git-branch[1] for details. -t:: --track::
@@ -114,13 +113,6 @@ the conflicted merge in the specified paths. "merge" (default) and "diff3" (in addition to what is shown by "merge" style, shows the original contents). -<new_branch>:: - Name for the new branch. - -<tree-ish>:: - Tree to checkout from (when paths are given). If not specified, - the index will be used. - <branch>:: Branch to checkout (when no paths are given); may be any object ID that resolves to a commit. Defaults to HEAD.
@@ -132,6 +124,18 @@ As a special case, the `"@\{-N\}"` syntax for the N-th last branch checks out the branch (instead of detaching). You may also specify `-` which is synonymous with `"@\{-1\}"`. +<new_branch>:: + Name for the new branch. + +<start_point>:: + The name of a commit at which to start the new branch; see + linkgit:git-branch[1] for details. Defaults to HEAD. + +<tree-ish>:: + Tree to checkout from (when paths are given). If not specified, + the index will be used. + + Detached HEAD -------------
--
1.6.3.rc0.148.g141203.dirty
From: Jeff King <hidden>
Date: 2016-06-15 22:46:36
In the code we literally stick "refs/heads/" on the front and see if it resolves, so that is probably the best explanation. Signed-off-by: Jeff King <redacted> --- I hope this helps a little bit with Mark's confusion. But while writing it, I really think it would be a simpler rule to say "if it's in refs/heads/, then it's a branch" (which is similar to what Mark suggested earlier). So "git checkout refs/heads/master" would be identical to "git checkout master". That would require a code change, though. Documentation/git-checkout.txt | 10 +++++----- 1 files changed, 5 insertions(+), 5 deletions(-)
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 4a1fb53..ad4b31e 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt@@ -114,11 +114,11 @@ the conflicted merge in the specified paths. "merge" style, shows the original contents). <branch>:: - Branch to checkout (when no paths are given); may be any object - ID that resolves to a commit. Defaults to HEAD. -+ -When this parameter names a non-branch (but still a valid commit object), -your HEAD becomes 'detached'. + Branch to checkout; if it refers to a branch (i.e., a name that, + when prepended with "refs/heads/", is a valid ref), then that + branch is checked out. Otherwise, if it refers to a valid + commit, your HEAD becomes "detached" and you are no longer on + any branch (see below for details). + As a special case, the `"@\{-N\}"` syntax for the N-th last branch checks out the branch (instead of detaching). You may also specify
--
1.6.3.rc0.148.g141203.dirty