Ramkumar Ramachandra <artag...@gmail.com> writes:

>  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.

> +
> +* `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

>  * `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.


> +* `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),


        ... 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.

To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Reply via email to