threads / patch / 9905
Subject: [PATCH 0/4] Make the documentation consistent for --track and --notrack
Hi,
Here is the patchset I sent before, hopefully in a format more palatable to the list.
The first three patches try to improve the documentation for git-branch and git-checkout, adding docs for --track and --notrack to git-branch.txt, and improving the ones that were in git-checkout.txt.
The last patch is for git-pull.sh; it gives the user a hint of what to do when there's no branch configured to merge from.
Federico
[PATCH 1/4] Mention that git-branch will not automatically check out the new branch
Signed-off-by: Federico Mena Quintero <federico@gnu.org> --- Documentation/git-branch.txt | 4 +++- 1 files changed, 3 insertions(+), 1 deletions(-)
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 33bc31b..47e6f49 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -24,7 +24,9 @@ and option `-a` shows both. In its second form, a new branch named <branchname> will be created. It will start out with a head equal to the one given as <start-point>. If no <start-point> is given, the branch will be created with a head -equal to that of the currently checked out branch. +equal to that of the currently checked out branch. Note that this +will create the new branch, but it will not switch the working tree to +it; use "git checkout <newbranch>" to switch to the new branch. When a local branch is started off a remote branch, git can setup the branch so that gitlink:git-pull[1] will appropriately merge from that
-- 1.5.2.4
[PATCH 2/4] Copy the docs for --track and --notrack from git-checkout to git-branch
The docs for git-branch did not mention --track and --notrack in the OPTIONS section.
Signed-off-by: Federico Mena Quintero <federico@gnu.org> --- Documentation/git-branch.txt | 14 ++++++++++++++ 1 files changed, 14 insertions(+), 0 deletions(-)
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 47e6f49..8b98b52 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -93,6 +93,20 @@ OPTIONS --no-abbrev:: Display the full sha1s in output listing rather than abbreviating them. +--track:: + Set up configuration so that git-pull will automatically + retrieve data from the remote branch, otherwise you'll have to + use "git pull <url>" explicitly. Set the + branch.autosetupmerge configuration variable to true if you + want git-checkout and git-branch to always behave as if + '--track' were given. + +--no-track:: + When -b is given and a branch is created off a remote branch, + set up configuration so that git-pull will not retrieve data + from the remote branch, ignoring the branch.autosetupmerge + configuration variable. + <branchname>:: The name of the branch to create or delete. The new branch name must pass all checks defined by
-- 1.5.2.4
[PATCH 3/4] Mention the parameters that git-pull would need to be equivalent to a --track in the git-checkout docs
To be consistent with the git-branch docs.
Signed-off-by: Federico Mena Quintero <federico@gnu.org> --- Documentation/git-checkout.txt | 3 ++- 1 files changed, 2 insertions(+), 1 deletions(-)
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 734928b..6f22626 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -50,7 +50,8 @@ OPTIONS --track:: When -b is given and a branch is created off a remote branch, set up configuration so that git-pull will automatically - retrieve data from the remote branch. Set the + retrieve data from the remote branch, otherwise you'll have to + use "git pull <url>" explicitly. Set the branch.autosetupmerge configuration variable to true if you want git-checkout and git-branch to always behave as if '--track' were given.
-- 1.5.2.4
Junio C HamanoRe: [PATCH 3/4] Mention the parameters that git-pull would need to be equivalent to a --track in the git-checkout docs
Federico Mena Quintero <federico@novell.com> writes:
> To be consistent with the git-branch docs. > > Signed-off-by: Federico Mena Quintero <federico@gnu.org> > --- > Documentation/git-checkout.txt | 3 ++- > 1 files changed, 2 insertions(+), 1 deletions(-) > > diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt > index 734928b..6f22626 100644 > --- a/Documentation/git-checkout.txt > +++ b/Documentation/git-checkout.txt > @@ -50,7 +50,8 @@ OPTIONS > --track:: > When -b is given and a branch is created off a remote branch, > set up configuration so that git-pull will automatically > - retrieve data from the remote branch. Set the > + retrieve data from the remote branch, otherwise you'll have to > + use "git pull <url>" explicitly. Set the > branch.autosetupmerge configuration variable to true if you > want git-checkout and git-branch to always behave as if > '--track' were given.
Hmph.
I'd rather make them consistent by dropping the not-so-correct "otherwise" phrase from all three copies. It is not "otherwise you'll have to", but "instead you can".
[PATCH 0/4] Another round of the --track patches
On Tue, 2007-09-18 at 15:38 -0700, Junio C Hamano wrote:
> Federico Mena Quintero <federico@novell.com> writes: > > - retrieve data from the remote branch. Set the > > + retrieve data from the remote branch, otherwise you'll have to > > + use "git pull <url>" explicitly. Set the > > branch.autosetupmerge configuration variable to true if you > > want git-checkout and git-branch to always behave as if > > '--track' were given. > > Hmph. > > I'd rather make them consistent by dropping the not-so-correct > "otherwise" phrase from all three copies. It is not "otherwise > you'll have to", but "instead you can".
Sure, I've added better wording now.
> I am inclined to suggest rewording the message like this, and > make this condition an error (i.e. "exit 1"):
[snip]
I like that message much better, and it's nice that it gives you the snippet to put in your config file. This is in patch 4/4.
Thanks for the review; I hope this can make it in now ;)
Federico
[PATCH 1/4] Say when --track is useful in the git-checkout docs.
The documentation used to say what the option does, but it didn't mention a use case.
Signed-off-by: Federico Mena Quintero <federico@gnu.org> --- Documentation/git-checkout.txt | 4 +++- 1 files changed, 3 insertions(+), 1 deletions(-)
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 734928b..dbd1a4a 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -50,7 +50,9 @@ OPTIONS --track:: When -b is given and a branch is created off a remote branch, set up configuration so that git-pull will automatically - retrieve data from the remote branch. Set the + retrieve data from the remote branch. Use this if you always + pull from the same remote branch into the new branch, or if you + don't want to use "git pull <repository> <refspec>" explicitly. Set the branch.autosetupmerge configuration variable to true if you want git-checkout and git-branch to always behave as if '--track' were given.
-- 1.5.2.4
[PATCH 1/4] Add documentation for --track and --no-track to the git-branch docs.
Signed-off-by: Federico Mena Quintero <federico@gnu.org> --- Documentation/git-branch.txt | 15 +++++++++++++++ 1 files changed, 15 insertions(+), 0 deletions(-)
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 33bc31b..e9c12f9 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -91,6 +91,21 @@ OPTIONS --no-abbrev:: Display the full sha1s in output listing rather than abbreviating them. +--track:: + Set up configuration so that git-pull will automatically + retrieve data from the remote branch. Use this if you always + pull from the same remote branch into the new branch, or if you + don't want to use "git pull <repository> <refspec>" explicitly. Set the + branch.autosetupmerge configuration variable to true if you + want git-checkout and git-branch to always behave as if + '--track' were given. + +--no-track:: + When -b is given and a branch is created off a remote branch, + set up configuration so that git-pull will not retrieve data + from the remote branch, ignoring the branch.autosetupmerge + configuration variable. + <branchname>:: The name of the branch to create or delete. The new branch name must pass all checks defined by
-- 1.5.2.4
Re: [PATCH 1/4] Add documentation for --track and --no-track to the git-branch docs.
Arrrr... this should be "[PATCH 2/4]", of course. Sorry for the confusion.
Federico
[PATCH 3/4] Note that git-branch will not automatically checkout the new branch
Signed-off-by: Federico Mena Quintero <federico@gnu.org> --- Documentation/git-branch.txt | 4 ++++ 1 files changed, 4 insertions(+), 0 deletions(-)
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index e9c12f9..53c1158 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -26,6 +26,10 @@ It will start out with a head equal to the one given as <start-point>. If no <start-point> is given, the branch will be created with a head equal to that of the currently checked out branch. +Note that this will create the new branch, but it will not switch the +working tree to it; use "git checkout <newbranch>" to switch to the +new branch. + When a local branch is started off a remote branch, git can setup the branch so that gitlink:git-pull[1] will appropriately merge from that remote branch. If this behavior is desired, it is possible to make it
-- 1.5.2.4
[PATCH 4/4] Make git-pull complain and give advice when there is nothing to pull from
Signed-off-by: Federico Mena Quintero <federico@gnu.org> --- git-pull.sh | 22 ++++++++++++++++++---- 1 files changed, 18 insertions(+), 4 deletions(-)
diff --git a/git-pull.sh b/git-pull.sh index c3f05f5..74bfc16 100755 --- a/git-pull.sh +++ b/git-pull.sh @@ -97,10 +97,24 @@ case "$merge_head" in esac curr_branch=${curr_branch#refs/heads/} - echo >&2 "Warning: No merge candidate found because value of config option - \"branch.${curr_branch}.merge\" does not match any remote branch fetched." - echo >&2 "No changes." - exit 0 + echo >&2 "You asked me to pull without telling me which branch you" + echo >&2 "want to merge with, and 'branch.${curr_branch}.merge' in" + echo >&2 "your configuration file does not tell me either. Please" + echo >&2 "name which branch you want to merge on the command line and" + echo >&2 "try again (e.g. 'git pull <repository> <refspec>')." + echo >&2 "See git-pull(1) for details on the refspec." + echo >&2 + echo >&2 "If you often merge with the same branch, you may want to" + echo >&2 "configure the following variables in your configuration" + echo >&2 "file:" + echo >&2 + echo >&2 " branch.${curr_branch}.remote = <nickname>" + echo >&2 " branch.${curr_branch}.merge = <remote-ref>" + echo >&2 " remote.<nickname>.url = <url>" + echo >&2 " remote.<nickname>.fetch = <refspec>" + echo >&2 + echo >&2 "See git-config(1) for details." + exit 1 ;; ?*' '?*) if test -z "$orig_head"
-- 1.5.2.4
[PATCH 4/4] Make git-pull give hints on what to do when there is no branch to merge from
Signed-off-by: Federico Mena Quintero <federico@gnu.org> --- git-pull.sh | 6 +++++- 1 files changed, 5 insertions(+), 1 deletions(-)
diff --git a/git-pull.sh b/git-pull.sh index 5e96d1f..7beef4d 100755 --- a/git-pull.sh +++ b/git-pull.sh @@ -98,7 +98,11 @@ case "$merge_head" in curr_branch=${curr_branch#refs/heads/} echo >&2 "Warning: No merge candidate found because value of config option - \"branch.${curr_branch}.merge\" does not match any remote branch fetched." + \"branch.${curr_branch}.merge\" does not match any remote branch fetched. + This branch is not set up to track any other branches. Please name which + branch you want to merge from on the command line, or if you almost always + want to merge from the same branch, then set this up with + \"git branch --track\"." echo >&2 "No changes." exit 0 ;;
-- 1.5.2.4
Junio C HamanoRe: [PATCH 4/4] Make git-pull give hints on what to do when there is no branch to merge from
Federico Mena Quintero <federico@novell.com> writes:
> Signed-off-by: Federico Mena Quintero <federico@gnu.org>
> ---
> git-pull.sh | 6 +++++-
> 1 files changed, 5 insertions(+), 1 deletions(-)
>
> diff --git a/git-pull.sh b/git-pull.sh
> index 5e96d1f..7beef4d 100755
> --- a/git-pull.sh
> +++ b/git-pull.sh
> @@ -98,7 +98,11 @@ case "$merge_head" in
> curr_branch=${curr_branch#refs/heads/}
>
> echo >&2 "Warning: No merge candidate found because value of config option
> - \"branch.${curr_branch}.merge\" does not match any remote branch fetched."
> + \"branch.${curr_branch}.merge\" does not match any remote branch fetched.
> + This branch is not set up to track any other branches. Please name which
> + branch you want to merge from on the command line, or if you almost always
> + want to merge from the same branch, then set this up with
> + \"git branch --track\"."This is a nice attempt, but can you use "git branch --track" to set this? What does the command line look like?
This error can come when branch.<foo>.merge does not match what remote.<bar>.fetch says (where branch.<foo>.remote is <bar>), but it is my understanding that the builtin-fetch work by Daniel and Shawn would fetch branch.<foo>.merge as well to reduce this error. Another possibility is when the user does not have any branch.<foo>.merge.
I am inclined to suggest rewording the message like this, and make this condition an error (i.e. "exit 1"):
You asked me to pull without telling me which branch you
want to merge with, and 'branch.${curr_branch}.merge' in
your configuration file does not tell me either. Please
name which branch you want to merge on the command line and
try again. If you often merge with the same branch, you may want to
configure the following variables in your configuration
file: branch.${curr_branch}.remote = <nickname>
branch.${curr_branch}.merge = <remote-ref>
remote.<nickname>.url = <url>
remote.<nickname>.fetch = <refspec>See git-config(1) for details.