Re: [RFC/PATCH v2] pull: add --set-upstream

["Philip Oakley" <philipoakley@iee.org>]

From: "Erwan Mathoniere" <erwan.mathoniere@grenoble-inp.org>
> Implement `git pull [--set-upstream | -u] <remote> <refspecs>` that set
> tracking to the remote branch the user just pulled from.
>
> After successfully pulling from `<remote>`, for each `<refspec>`
> described in format `<remote_branch>:<local_branch>`, set
> `branch.<local_branch>.remote` to `<remote>` and
> `branch.<local_branch>.merge` to `refs/heads/<remote_branch>`. If
> `<refspec>` lacks `<local_branch>` in the previous format or directly
> refers to a branch, use the current branch as `<local_branch>` in the
> above configuration setting.
>
> `git push` has already its `--set-upstream`, it makes sense to have its
> symmetrical for `git pull`.
>
> For a beginner, when trying to use argumentless `git pull` without
> tracking information set, advising to use
> `git branch --set-upstream-to` to set upstream can be quite confusing.
> Using this `git pull --set-upstream` is easier and more natural.
>
> Signed-off-by: Erwan Mathoniere <erwan.mathoniere@grenoble-inp.org>
> Signed-off-by: Jordan De Gea <jordan.de-gea@grenoble-inp.org>
> Signed-off-by: Matthieu Moy <matthieu.moy@grenoble-inp.fr>
> ---
>
> Changes from v1:
> - Code reshaped to :
>  * warn + no-op when pulling from or to something that isn't a branch
> or a configured remote
>  * set upstream only after successfully merging/rebasing
> - More relevant documentation
> - Tests reshaped to be more independent from each others
> - More tests (tags, detached heads, non-configured remote...)
>
>
> For now, the documentation is quite hard to understand, but I didn't
> figure how to explain without using too technical words. Should it stay
> as it is or should I write something similar the above commit message?
>
> Allowing to set non-configured repository as upstream isn't easy to
> handle since the type of refspec must be checked and this is done by
> verifying the existence of the remote-tracking branch at
> `refs/remotes/<remote>/<branch>`.
>
>
> Documentation/git-pull.txt |  18 +++++
> builtin/pull.c             | 106 ++++++++++++++++++++++++++++-
> t/t5544-pull-upstream.sh   | 164 
> +++++++++++++++++++++++++++++++++++++++++++++
> 3 files changed, 285 insertions(+), 3 deletions(-)
> create mode 100755 t/t5544-pull-upstream.sh
>
> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
> index d033b25..6ae5e58 100644
> --- a/Documentation/git-pull.txt
> +++ b/Documentation/git-pull.txt
> @@ -93,6 +93,24 @@ OPTIONS
>  has to be called afterwards to bring the work tree up to date with the
>  merge result.
>
> +-u::
> +--set-upstream::
> + After successfully pulling from explicitly given <repository> and

s/from explicitly/from an explicitly/

> + <refspecs>, set the configuration of the local branches pulled on, so

s/branches pulled on/branches that were pulled/

> + that each one tracks the remote branch pulled from. If a configuration
> + already exists, it is overwriten. For example, with `git pull -u origin
> + branch` the current branch will track `branch` from `origin`.
> ++
> +If two or more branches are pulled on the same local branch, only the 
> last one
> +in arguments will be tracked.

Is this specific to this pull --setupstream or a general worning ? i.e. that 
a second entry is created in the config file, or that only the last branch 
refspec will be added?

> ++
> +The given <repository> must be a configured remote. Can only set tracking 
> to
> +remote branches (e.g. can't set upstream to remote HEAD).
> ++
> +Works symmetrically as `--set-upstream` for linkgit:git-push[1]. Allow 
> using
> +argumentless linkgit:git-pull[1] and other commands.  For more 
> information, see
> +`branch.<name>.merge` in linkgit:git-config[1].
> +
> Options related to merging
> ~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> diff --git a/builtin/pull.c b/builtin/pull.c
[snip]