From 70e966477aacf46d4d6cb8c01f8bd9a9ceb5e80f Mon Sep 17 00:00:00 2001 From: Jeff King Date: Mon, 13 Apr 2009 07:11:16 -0400 Subject: [PATCH 1/5] doc: clarify --no-track option 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 Signed-off-by: Junio C Hamano --- 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 ba3dea6840..19f1b0d9f9 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 :: Only list branches which contain the specified commit. diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 223ea9caef..4992fc61eb 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 From 167d7445433bb6dfac6b844b99ae455129326141 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Mon, 13 Apr 2009 07:11:56 -0400 Subject: [PATCH 2/5] doc: refer to tracking configuration as "upstream" 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 Signed-off-by: Junio C Hamano --- 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 19f1b0d9f9..cbd4275871 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 - " 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 :: diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 4992fc61eb..16d3c872a0 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:: From 26d22dc64ad2373eb918f004a1d0ba2649e7e1a5 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Mon, 13 Apr 2009 07:18:52 -0400 Subject: [PATCH 3/5] doc/checkout: refer to git-branch(1) as appropriate 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 Signed-off-by: Junio C Hamano --- Documentation/git-checkout.txt | 28 +++++++++------------------- 1 file changed, 9 insertions(+), 19 deletions(-) diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 16d3c872a0..22ad10d952 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 [-l]] [-m] [] +'git checkout' [-q] [-f] [-m] [-b ] [] 'git checkout' [-f|--ours|--theirs|-m|--conflict=