Re: [PATCH 2/6] config doc: rewrite push.default section
On Thu, Jun 20, 2013 at 5:27 AM, Junio C Hamano wrote: > +* `simple` - a safer version of `current`; push the current branch > + to update a branch with the same name on the receiving end, with a > + safety feature: in central workflows, error out if your current > + branch is not set to integrate with the branch with the same name, > + to ensure that a `push` and a `push` are symmetrical. to ensure that a `push` and a `pull` are symmetrical. Otherwise, this looks good to me. ...Johan -- Johan Herland, www.herland.net -- 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
Re: [PATCH 2/6] config doc: rewrite push.default section
Junio C Hamano writes:
> or something like that.
Just for a completeness, in a patch form:
Documentation/config.txt | 66
1 file changed, 39 insertions(+), 27 deletions(-)
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 81628e8..4b7fc54 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -1833,37 +1833,49 @@ push.default::
`upstream` is probably what you want. Possible values are:
+
--
+
* `nothing` - do not push anything (error out) unless a refspec is
- explicitly given. Very safe, but not very convenient.
+ explicitly given. This is primarily meant for people who want to
+ avoid mistakes by always being explicit.
* `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).
-
-* `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. The name
- "upstream" refers to "@{u[pstream]}" in linkgit:gitrevisions[7],
- which makes sense only if both branch.$branch.remote and
- branch.$branch.merge are set. It makes sure that a `push` is
- symmetrical to `pull` in central workflows, and cannot be used in
- non-central workflows.
-
-* `simple` - a safer version of `current`; push the current branch to
- update a branch with the same name on the receiving end, with a
- safety feature: in central workflows, error out if
- branch.$branch.merge is set and not equal to $branch, to make sure
- that a `push` and `push` are never asymmetrical. 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).
- Well-suited for those who want to batch-update a specific set of
- branches they consistently work on. Use with caution, especially
- when pushing with '--force'. Equivalent to pushing the refspec ":".
- This is currently the default, but Git 2.0 will change the default
- to `simple`.
+ workflows.
+
+* `upstream` - push the current branch back to the branch whose
+ changes are usually integrated into the current branch (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` - a safer version of `current`; push the current branch
+ to update a branch with the same name on the receiving end, with a
+ safety feature: in central workflows, error out if your current
+ branch is not set to integrate with the branch with the same name,
+ to ensure that a `push` and a `push` are symmetrical.
++
+This mode will become the default in Git 2.0.
+
+* `matching` - push all branches having the same name 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.
++
+This is currently the default, but Git 2.0 will change the default
+to `simple`.
+
--
rebase.stat::
--
1.8.3.1-674-gb27e881
--
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
Re: [PATCH 2/6] config doc: rewrite push.default section
Ramkumar Ramachandra 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..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
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
