Re: [PATCH 2/6] config doc: rewrite push.default section

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 19, 2013, 19:55 UTC
Message-ID: <7v7ghpzxhu.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1371640304-26019-3-git-send-email-artagnon@gmail.com>

Ramkumar Ramachandra <artagnon@gmail.com> writes:

Show 25 quoted lines

>  push.default::
> +	Defines the action `git push` should take if no refspec is
> +	explicitly given.  Different values are well-suited for
> +	specific workflows; for instance, in a purely central workflow
> +	(i.e. the fetch source is equal to the push destination),
> +	`upstream` is probably what you want.  Possible values are:
>  +
>  --
> -* `nothing` - do not push anything.
> -* `matching` - push all branches having the same name in both ends.
> -  This is for those who prepare all the branches into a publishable
> -  shape and then push them out with a single command.  It is not
> -  appropriate for pushing into a repository shared by multiple users,
> -  since locally stalled branches will attempt a non-fast forward push
> -  if other users updated the branch.
> -  +
> -  This is currently the default, but Git 2.0 will change the default
> -  to `simple`.
> -* `upstream` - push the current branch to its upstream branch
> -  (`tracking` is a deprecated synonym for this).
> -  With this, `git push` will update the same remote ref as the one which
> -  is merged by `git pull`, making `push` and `pull` symmetrical.
> -  See "branch.<name>.merge" for how to configure the upstream branch.
> +* `nothing` - do not push anything (error out) unless a refspec is
> +  explicitly given.  Very safe, but not very convenient.

Drop the last one, that does not add any value to the description.

Show 5 quoted lines

> +
> +* `current` - push the current branch to update a branch with the same
> +  name on the receiving end.  Works in both central and non-central
> +  workflows.  Equivalent to pushing the refspec "$branch" ($branch is
> +  the name of the current branch).

I do not think this is a place to teach how various refspecs are spelled, but if you want to, then giving a complete command line would be more appropriate. Otherwise I'd suggest dropping everything after "Equivalent to...".

> +* `upstream` - push the current branch to a branch with the name
> +  branch.$branch.merge on the receiving end, and error out if the push
> +  destination is not the same as branch.$branch.remote.

While the above may be technically accurate, a mechanical definition help readers who read this for the first time may not be very helpful. What does the operation mean?

	push the current branch back to the branch whose changes are
	usually integrated into the current branch with "git pull"
	(which is called @{upstream}).

	this mode only makes sense if you are pushing to the same
	repository you would normally "pull" from (i.e. central
	workflow).

>  * `simple` - like `upstream`, but refuses to push if the upstream
>    branch's name is different from the local one. This is the safest
>    option and is well-suited for beginners. It will become the default
>    in Git 2.0.

OK.

> +* `matching` - push all branches having the same name on both ends
> +  (essentially ignoring all newly created local branches).

That misses the 'essense' of 'matching' by a wide margin, as "newly created" does not have anything to do with it. Topic branches you decided not to push long time ago and haven't pushed out so far will not suddenly get pushed with "git push", either.

Think of it this way. Among your local branches, there are classes of branches that:

 (1) you would want to push now,
 (2) you would want to push when they are done, and
 (3) you would never want to push.

Other "push only single branch" modes make this distinction by limiting the push to only the first class (those you would want to push now), but it further limits that set to a single branch, which is the current one. It is up to you to differentiate class 2+3 (those you do not want to push now) from class 1 (the single one you do want to push) and you indicate that choice by running 'git push' only when you are on the branch you want to push out.

The 'matching' mode allows you to "configure" by having the other side remember which ones are in the class 1 (i.e. those that you will push out when you say 'git push'). Instead of keeping a list of branches to be pushed in local configuration variable, you use the set of branches your publishing point has. It has a limitation that you are not allowed to have the second category (i.e. at this point of running 'git push' they are not ready to be pushed out), though.

Perhaps

	... on both ends.  This makes the repository you are pushing
	to remember the set of branches that will be pushed out
	(e.g. if you always push 'maint' and 'master' there and no
	other branches, the repository you push to will have these
	two branches, and your local 'maint' and 'master' will be
	pushed there).

        To use this mode effectively, you have to make sure _all_
	the branches you would push out are ready to be pushed out
	before running 'git push', as the whole point of this mode
	is to allow you to push all of the branches in one go.  If
	you usually finish work on only one branch and push out the
	result, while other branches are unfinished, this mode is
	not for you.  Also this mode is not suitable for pushing
	into a shared central repository, as other people may add
	new branches there, or update the tip of existing branches
	outside your control.

or something like that.