From 185c0874b1adea696b47d2fb78aca9a282a86abb Mon Sep 17 00:00:00 2001 From: Matthieu Moy Date: Tue, 24 Apr 2012 09:50:00 +0200 Subject: Documentation: explain push.default option a bit more 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. Signed-off-by: Matthieu Moy Signed-off-by: Junio C Hamano --- Documentation/config.txt | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) (limited to 'Documentation/config.txt') diff --git a/Documentation/config.txt b/Documentation/config.txt index fb386abc51..5f14871d2a 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1680,12 +1680,24 @@ push.default:: line. Possible values are: + * `nothing` - do not push anything. -* `matching` - push all matching branches. - All branches having the same name in both ends are considered to be - matching. This is the default. +* `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. + 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. * `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. 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 -- cgit v1.2.3 From 628ab0ea1046800b9520c07d809db886b1ec3693 Mon Sep 17 00:00:00 2001 From: Matthieu Moy Date: Tue, 24 Apr 2012 09:50:01 +0200 Subject: Undocument deprecated alias 'push.default=tracking' It's been deprecated since 53c4031 (Johan Herland, Wed Feb 16 2011, push.default: Rename 'tracking' to 'upstream'), so it's OK to remove it from documentation (even though it's still supported) to make the explanations more readable. Signed-off-by: Matthieu Moy Signed-off-by: Junio C Hamano --- Documentation/config.txt | 1 - 1 file changed, 1 deletion(-) (limited to 'Documentation/config.txt') diff --git a/Documentation/config.txt b/Documentation/config.txt index 5f14871d2a..9617c53951 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1690,7 +1690,6 @@ push.default:: 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. -* `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 -- cgit v1.2.3 From b55e67752242b449a4577c05341fd6b2fea4d310 Mon Sep 17 00:00:00 2001 From: Matthieu Moy Date: Tue, 24 Apr 2012 09:50:03 +0200 Subject: push: introduce new push.default mode "simple" When calling "git push" without argument, we want to allow Git to do something simple to explain and safe. push.default=matching is unsafe when used to push to shared repositories, and hard to explain to beginners in some contexts. It is debatable whether 'upstream' or 'current' is the safest or the easiest to explain, so introduce a new mode called 'simple' that is the intersection of them: push to the upstream branch, but only if it has the same name remotely. If not, give an error that suggests the right command to push explicitely to 'upstream' or 'current'. A question is whether to allow pushing when no upstream is configured. An argument in favor of allowing the push is that it makes the new mode work in more cases. On the other hand, refusing to push when no upstream is configured encourages the user to set the upstream, which will be beneficial on the next pull. Lacking better argument, we chose to deny the push, because it will be easier to change in the future if someone shows us wrong. Original-patch-by: Jeff King Signed-off-by: Matthieu Moy Signed-off-by: Junio C Hamano --- Documentation/config.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'Documentation/config.txt') diff --git a/Documentation/config.txt b/Documentation/config.txt index 9617c53951..7f5ad1ce06 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1686,13 +1686,16 @@ push.default:: 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. +* `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. * `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..merge" for how to configure the upstream branch. * `current` - push the current branch to a branch of the same name. + - The `current` and `upstream` modes are for those who want to + 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 -- cgit v1.2.3 From 67804c2731f9028ac246f7cea6fd9652386bab33 Mon Sep 17 00:00:00 2001 From: Matthieu Moy Date: Tue, 24 Apr 2012 09:50:05 +0200 Subject: push: document the future default change for push.default (matching -> simple) It is too early to start warning loudly about the future default change in favor of 'simple', since many users use different versions of Git, and would be harmed if we advised them to explicitely set 'push.default=simple' when using old versions of Git. Still, we want to document the upcomming change so that: * Users who may be affected by the change get one more chance to know it in advance. * We actually commit to changing the default, and avoid repeating past errors. Signed-off-by: Matthieu Moy Signed-off-by: Junio C Hamano --- Documentation/config.txt | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) (limited to 'Documentation/config.txt') diff --git a/Documentation/config.txt b/Documentation/config.txt index 7f5ad1ce06..f724fc64b2 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1685,10 +1685,14 @@ push.default:: 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. + if other users updated the branch. + + + This is currently the default, but Git 2.0 will change the default + to `simple`. * `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. + option and is well-suited for beginners. It will become the default + in Git 2.0. * `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. -- cgit v1.2.3 From f4d80d2639f8ef55c99c3b035c0312969acc7f01 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Tue, 24 Apr 2012 12:21:12 -0700 Subject: push.default doc: explain simple after upstream As the "simple" mode is described in terms of what "upstream" does, swap the order of these two entries so that the reader sees "upstream" first and then reads "simple" with the knowledge of what "upstream" does. Signed-off-by: Junio C Hamano --- Documentation/config.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'Documentation/config.txt') diff --git a/Documentation/config.txt b/Documentation/config.txt index f724fc64b2..6a4c130602 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1689,14 +1689,14 @@ push.default:: + This is currently the default, but Git 2.0 will change the default to `simple`. -* `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. * `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..merge" for how to configure the upstream branch. +* `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. + The `simple`, `current` and `upstream` modes are for those who want to -- cgit v1.2.3