Matthieu Moy <Matthieu.Moy@xxxxxxx> writes:
> The previous documentation was explaining _what_ the options were doing,
> but were of little help explaining _why_ a user should set his default to
> either of the options.
Thanks.
> * `nothing` - do not push anything.
> +* `matching` - push all branches having the same name in both ends.
> + This allows those who prepare all the branches into a publishable
> + shape to push them out to a non-shared repository with a single
> + command. This is well suited when pushing to a non-shared
> + repository, but may give surprising results when used on a
> + repository shared by multiple users, since locally stalled
> + branches will attempt a non-fast forward push if other users
> + updated the branch remotely. This is the default.
The thought does not flow smoothly with the repetition of "non-shared"
here. How about rephrasing it a bit, perhaps like this?
* `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 the default.
> +* `upstream` - push the current branch to its upstream branch. See
> + "branch.<name>.merge" for how to configure the upstream branch. This
> + makes `git push` and `git pull` symmetrical in the sense that `push`
> + will update the same remote ref as the one which is merged by
> + `git pull`.
Reordering the sentences may make it read better; first tell the reader
why and what enough so that they can decide if this is good for her and
then tell her how to configure it.
* `upstream` - push the current branch to its upstream branch.
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.
> * `tracking` - deprecated synonym for `upstream`.
> * `current` - push the current branch to a branch of the same name.
> + +
> + The `current` and `upstream` modes are for those who want to
> + push out a single branch after finishing work, even when the other
> + branches are not yet ready to be pushed out. They are safe when
> + pushing to a shared repository.
Do we really want to say "safe" here? I think it is misleading in
multiple ways.
- If your current branch has a name differnt from its upstream, using
`current` when you meant `upstream` may result in the embarrasing
fast forward discussed elsewhere, which is hardly "safe".
- If you always make everything on your end ready before pushing things
out, `matching` may attempt to update remote branches other than the
one that corresponds to your current branch, but that is exactly what
you want to see---there is no danger here. You can make it dangerous
with --force, but that is a separate issue.
- An attempt to push a stale branch in all cases will error out without
causing damage to the remote repository. If you do not keep your
branches up-to-date and still use `matching`, you have more chance of
seeing this when used against a shared repository. It is unclear if
the use of word "safe" in the above description means this "you are
behind" error "a risk to be avoided", but
- if so, `current` or `upstream` will see the same error in a shared
repository where the same branch is updated by multiple people, so
"They are safe" is not quite correct; and
- if not, then `matching` is not less safe than others (it is just
as safe and unsafe as `current`).
There is a high correlation between use of shared repository and the
style of "working on one branch at a time, pushing the result as soon as
that single branch is OK", so I am perfectly fine with saying that these
single-branch modes are most likely what people want to use when working
with a shared repository, but I do not think `safety` has much to do
with the choice.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html