config doc: rewrite push.default section
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 <artagnon@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ramkumar Ramachandra committed
Jun 19, 2013 at 16:41 UTC
87a70e4ce8bb3bdbb3048a5eb837f6b5b2eff8f9
1 file changed
+44
-28
Documentation/config.txt
+44
-28
@@ -1826,39 +1826,55 @@ pull.twohead::
1826
The default merge strategy to use when pulling a single branch.
1827
1828
push.default::
1829
- Defines the action `git push` should take if no refspec is given
1830
- on the command line, no refspec is configured in the remote, and
1831
- no refspec is implied by any of the options given on the command
1832
- line. Possible values are:
1829
+ Defines the action `git push` should take if no refspec is
1830
+ explicitly given. Different values are well-suited for
1831
+ specific workflows; for instance, in a purely central workflow
1832
+ (i.e. the fetch source is equal to the push destination),
1833
+ `upstream` is probably what you want. Possible values are:
1834
+
1835
--
1835
-* `nothing` - do not push anything.
1836
-* `matching` - push all branches having the same name in both ends.
1837
- This is for those who prepare all the branches into a publishable
1838
- shape and then push them out with a single command. It is not
1839
- appropriate for pushing into a repository shared by multiple users,
1840
- since locally stalled branches will attempt a non-fast forward push
1841
- if other users updated the branch.
1842
- +
1843
- This is currently the default, but Git 2.0 will change the default
1844
- to `simple`.
1845
-* `upstream` - push the current branch to its upstream branch
1846
- (`tracking` is a deprecated synonym for this).
1847
- With this, `git push` will update the same remote ref as the one which
1848
- is merged by `git pull`, making `push` and `pull` symmetrical.
1849
- See "branch.<name>.merge" for how to configure the upstream branch.
1836
+
1837
+* `nothing` - do not push anything (error out) unless a refspec is
1838
+ explicitly given. This is primarily meant for people who want to
1839
+ avoid mistakes by always being explicit.
1840
+
1841
+* `current` - push the current branch to update a branch with the same
1842
+ name on the receiving end. Works in both central and non-central
1843
+ workflows.
1844
+
1845
+* `upstream` - push the current branch back to the branch whose
1846
+ changes are usually integrated into the current branch (which is
1847
+ called `@{upstream}`). This mode only makes sense if you are
1848
+ pushing to the same repository you would normally pull from
1849
+ (i.e. central workflow).
1850
+
1851
* `simple` - like `upstream`, but refuses to push if the upstream
1852
branch's name is different from the local one. This is the safest
1852
- option and is well-suited for beginners. It will become the default
1853
- in Git 2.0.
1854
-* `current` - push the current branch to a branch of the same name.
1855
---
1853
+ option and is well-suited for beginners.
1854
+
1857
-The `simple`, `current` and `upstream` modes are for those who want to
1858
-push out a single branch after finishing work, even when the other
1859
-branches are not yet ready to be pushed out. If you are working with
1860
-other people to push into the same shared repository, you would want
1861
-to use one of these.
1855
+This mode will become the default in Git 2.0.
1856
+
1857
+* `matching` - push all branches having the same name on both ends.
1858
+ This makes the repository you are pushing to remember the set of
1859
+ branches that will be pushed out (e.g. if you always push 'maint'
1860
+ and 'master' there and no other branches, the repository you push
1861
+ to will have these two branches, and your local 'maint' and
1862
+ 'master' will be pushed there).
1863
++
1864
+To use this mode effectively, you have to make sure _all_ the
1865
+branches you would push out are ready to be pushed out before
1866
+running 'git push', as the whole point of this mode is to allow you
1867
+to push all of the branches in one go. If you usually finish work
1868
+on only one branch and push out the result, while other branches are
1869
+unfinished, this mode is not for you. Also this mode is not
1870
+suitable for pushing into a shared central repository, as other
1871
+people may add new branches there, or update the tip of existing
1872
+branches outside your control.
1873
++
1874
+This is currently the default, but Git 2.0 will change the default
1875
+to `simple`.
1876
+
1877
+--
1878
1879
rebase.stat::
1880
Whether to show a diffstat of what changed upstream since the last