Re: [PATCH 1/7] Documentation: explain push.default option a bit more

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 23, 2012, 15:20 UTC
Message-ID: <xmqqr4velbkq.fsf@junio.mtv.corp.google.com>
In-Reply-To: <1335170284-30768-2-git-send-email-Matthieu.Moy@imag.fr>

Matthieu Moy <Matthieu.Moy@imag.fr> 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.

Show 9 quoted lines

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

Show 5 quoted lines

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

Show 7 quoted lines

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