[PATCH 2/6] config doc: rewrite push.default section
From: Ramkumar Ramachandra artag...@gmail.com
4d35924e (Merge branch 'rr/triangle', 2013-04-07) introduced support
for triangular workflows, but the push.default values still assume
central workflows.
Rewrite the descriptions of `nothing`, `current`, `upstream` and
`matching` for greater clarity, and explicitly explain how they
should behave in triangular workflows.
Leave `simple` as it is for the moment, as we plan to change its
meaning to accommodate triangular workflows in a later patch.
Signed-off-by: Ramkumar Ramachandra artag...@gmail.com
Signed-off-by: Junio C Hamano gits...@pobox.com
---
Documentation/config.txt | 72 +---
1 file changed, 44 insertions(+), 28 deletions(-)
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 7fd4035..5d8ff1a 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -1826,39 +1826,55 @@ pull.twohead::
The default merge strategy to use when pulling a single branch.
push.default::
- Defines the action `git push` should take if no refspec is given
- on the command line, no refspec is configured in the remote, and
- no refspec is implied by any of the options given on the command
- line. Possible values are:
+ 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. 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.
+
+* `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` - 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.
-* `current` - push the current branch to a branch of the same name.
---
+ option and is well-suited for beginners.
+
-The `simple`, `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. If you are working with
-other people to push into the same shared repository, you would want
-to use one of these.
+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::
Whether to show a diffstat of what changed upstream since the last
--
1.8.3.1-721-g0a353d3
--
To unsubscribe from this list: send the line unsubscribe git in
the body
Re: [PATCH 2/6] config doc: rewrite push.default section
On Thu, Jun 20, 2013 at 5:27 AM, Junio C Hamano gits...@pobox.com 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, jo...@herland.net 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
[PATCH 2/6] config doc: rewrite push.default section
4d3592 (Merge branch 'rr/triangle', 2013-04-07) introduced support for
triangular workflows in Git, but the push.default values still assume
central workflows. Rewrite the descriptions of `nothing`, `current`,
`upstream` and `matching` for greater clarity, and explicitly explaining
how they behave in triangular workflows. Leave `simple` as it is for
the moment, as we plan to change its meaning to accommodate triangular
workflows in a later patch.
Signed-off-by: Ramkumar Ramachandra artag...@gmail.com
---
Documentation/config.txt | 56 ++--
1 file changed, 30 insertions(+), 26 deletions(-)
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 7fd4035..9f04f74 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -1826,39 +1826,43 @@ pull.twohead::
The default merge strategy to use when pulling a single branch.
push.default::
- Defines the action `git push` should take if no refspec is given
- on the command line, no refspec is configured in the remote, and
- no refspec is implied by any of the options given on the command
- line. Possible values are:
+ 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.
+
+* `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` - 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.
-* `current` - push the current branch to a branch of the same name.
+
+* `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`.
--
-+
-The `simple`, `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. If you are working with
-other people to push into the same shared repository, you would want
-to use one of these.
rebase.stat::
Whether to show a diffstat of what changed upstream since the last
--
1.8.3.1.454.g30263f3.dirty
--
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 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
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.
Re: [PATCH 2/6] config doc: rewrite push.default section
Junio C Hamano gits...@pobox.com 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
