{"thread":{"id":"34163","subject":"[PATCH] config doc: rewrite push.default section","startedAt":"2013-06-16T10:06:28Z","lastAt":"2013-06-18T07:47:09Z","messageCount":12,"participants":["Ramkumar Ramachandra","Philip Oakley","Matthieu Moy","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"220995","messageId":"1371377188-18938-1-git-send-email-artagnon@gmail.com","threadId":"34163","inReplyTo":null,"subject":"[PATCH] config doc: rewrite push.default section","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-06-16T10:06:28Z","receivedAt":"2013-06-16T10:06:28Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Design by Junio.\n\nBy detaching descriptions from the implementation, we're only confusing\nusers. I've chosen to use the term \"central workflow\" to make the\ndescriptions terse and readable, although I've stayed way from\n\"triangular workflow\" (referred to as non-central workflow).\n\nYes, I hate writing documentation but I have no choice if I want to\nupdate the implementations to do something sane in triangular workflows.\n\nSigned-off-by: Ramkumar Ramachandra \n---\n I'll send in the implementation once we can agree that this is what\n we want.\n\n Documentation/config.txt | 51 ++++++++++++++++++++++++------------------------\n 1 file changed, 25 insertions(+), 26 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex 7fd4035..30350a3 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -1832,33 +1832,32 @@ push.default::\n \tline. Possible values are:\n +\n --\n-* `nothing` - do not push anything.\n-* `matching` - push all branches having the same name in both ends.\n- This is for those who prepare all the branches into a publishable\n- shape and then push them out with a single command. It is not\n- appropriate for pushing into a repository shared by multiple users,\n- since locally stalled branches will attempt a non-fast forward push\n- if other users updated the branch.\n- +\n- This is currently the default, but Git 2.0 will change the default\n- to `simple`.\n-* `upstream` - push the current branch to its upstream branch\n- (`tracking` is a deprecated synonym for this).\n- With this, `git push` will update the same remote ref as the one which\n- is merged by `git pull`, making `push` and `pull` symmetrical.\n- See \"branch..merge\" for how to configure the upstream branch.\n-* `simple` - like `upstream`, but refuses to push if the upstream\n- branch's name is different from the local one. This is the safest\n- option and is well-suited for beginners. It will become the default\n- in Git 2.0.\n-* `current` - push the current branch to a branch of the same name.\n+* `nothing` - error out unless a refspec is explicitly given.\n+\n+* `current` - push the refspec \"$HEAD\". HEAD is resolved early to a\n+ branch name (referred to as $HEAD). In other words, push the\n+ current branch to update a branch with the same name on the pushing\n+ side.\n+\n+* `upstream` - push the refspec \"$HEAD:branch.$HEAD.merge\", and error\n+ out if the push destination is not the same as branch.$HEAD.remote.\n+ The name \"upstream\" refers to the revision \"@{u[pstream]}\" in\n+ linkgit:gitrevisions[7]. It is useful in central workflows, to make\n+ the `push` symmetrical to `pull`.\n+\n+* `simple` - in central workflows, behaves like `upstream`, except\n+ that it errors out unless branch.$HEAD.merge is equal to $HEAD. In\n+ non-central workflows, behaves like `current`. It will become the\n+ default in Git 2.0.\n+\n+* `matching` - push the refspec \":\". In other words, push all\n+ branches having the same name in both ends, even if it means\n+ non-fast-forward updates. This is for those who prepare all the\n+ branches into a publishable shape and then push them out with a\n+ single command. Dangerous, and inappropriate unless you are the\n+ only person updating your push destination. This is currently the\n+ default, but Git 2.0 will change the default to `simple`.\n --\n-+\n-The `simple`, `current` and `upstream` modes are for those who want to\n-push out a single branch after finishing work, even when the other\n-branches are not yet ready to be pushed out. If you are working with\n-other people to push into the same shared repository, you would want\n-to use one of these.\n \n rebase.stat::\n \tWhether to show a diffstat of what changed upstream since the last\n-- \n1.8.3.1.443.g4fd77b9\n"},{"id":"220997","messageId":"89027CD773CE4BFC8C293D2454CE4AE5@PhilipOakley","threadId":"34163","inReplyTo":"1371377188-18938-1-git-send-email-artagnon@gmail.com","subject":"Re: [PATCH] config doc: rewrite push.default section","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2013-06-16T12:10:22Z","receivedAt":"2013-06-16T12:10:22Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Ramkumar Ramachandra\" \nSent: Sunday, June 16, 2013 11:06 AM\n> Design by Junio.\n>\n> By detaching descriptions from the implementation, we're only \n> confusing\n> users. I've chosen to use the term \"central workflow\" to make the\n> descriptions terse and readable, although I've stayed way from\n> \"triangular workflow\" (referred to as non-central workflow).\n\nA sentence, in the Documentation/config.txt, is needed to clarify the \nCentral workflow and any distinction with the non-central workflow(s). \nWe cannot assume the new reader has the same world view of that concept \n(they may be thinking it means we do a centralised VCS, not a DVCS with \na chosen central primary repo - assuming I have understood it \ncorrectly).\n\nIt took a while to bottom out the issues, so it is worth summarising the \nkey point(s) in the documentation to avoid having to repeat the \ndisussions ;-)\n\n>\n> Yes, I hate writing documentation but I have no choice if I want to\n> update the implementations to do something sane in triangular \n> workflows.\n>\n> Signed-off-by: Ramkumar Ramachandra \n> ---\n> I'll send in the implementation once we can agree that this is what\n> we want.\n>\n> Documentation/config.txt | 51 \n> ++++++++++++++++++++++++------------------------\n> 1 file changed, 25 insertions(+), 26 deletions(-)\n>\n> diff --git a/Documentation/config.txt b/Documentation/config.txt\n> index 7fd4035..30350a3 100644\n> --- a/Documentation/config.txt\n> +++ b/Documentation/config.txt\n> @@ -1832,33 +1832,32 @@ push.default::\n> line. Possible values are:\n> +\n> --\n> -* `nothing` - do not push anything.\n> -* `matching` - push all branches having the same name in both ends.\n> - This is for those who prepare all the branches into a publishable\n> - shape and then push them out with a single command. It is not\n> - appropriate for pushing into a repository shared by multiple users,\n> - since locally stalled branches will attempt a non-fast forward push\n> - if other users updated the branch.\n> - +\n> - This is currently the default, but Git 2.0 will change the default\n> - to `simple`.\n> -* `upstream` - push the current branch to its upstream branch\n> - (`tracking` is a deprecated synonym for this).\n> - With this, `git push` will update the same remote ref as the one \n> which\n> - is merged by `git pull`, making `push` and `pull` symmetrical.\n> - See \"branch..merge\" for how to configure the upstream branch.\n> -* `simple` - like `upstream`, but refuses to push if the upstream\n> - branch's name is different from the local one. This is the safest\n> - option and is well-suited for beginners. It will become the default\n> - in Git 2.0.\n> -* `current` - push the current branch to a branch of the same name.\n> +* `nothing` - error out unless a refspec is explicitly given.\n> +\n> +* `current` - push the refspec \"$HEAD\". HEAD is resolved early to a\n> + branch name (referred to as $HEAD). In other words, push the\n\ns/In other words,/That is,/\n'In other words' often indicates poor wording, while here the extra \nwords explicitly explain the effect.\n\n> + current branch to update a branch with the same name on the pushing\n> + side.\n\ns/pushing side/push destination/ for consistency with upstream wording \nused below.\n\n> +\n> +* `upstream` - push the refspec \"$HEAD:branch.$HEAD.merge\", and error\n> + out if the push destination is not the same as branch.$HEAD.remote.\n> + The name \"upstream\" refers to the revision \"@{u[pstream]}\" in\n> + linkgit:gitrevisions[7]. It is useful in central workflows, to \n> make\n> + the `push` symmetrical to `pull`.\n> +\n> +* `simple` - in central workflows, behaves like `upstream`, except\n> + that it errors out unless branch.$HEAD.merge is equal to $HEAD. In\n> + non-central workflows, behaves like `current`. It will become the\n> + default in Git 2.0.\n> +\n> +* `matching` - push the refspec \":\". In other words, push all\n> + branches having the same name in both ends, even if it means\n> + non-fast-forward updates. This is for those who prepare all the\n> + branches into a publishable shape and then push them out with a\n> + single command. Dangerous, and inappropriate unless you are the\n\n\"Dangerous and innappropriate\" (which it maybe for some) is too \njudgemental.\nPerhaps turn it around to a positive (unless -> only if).\n\n\"Useful if you are the..\"\n\n> + only person updating your push destination. This is currently the\n> + default, but Git 2.0 will change the default to `simple`.\n> --\n> -+\n> -The `simple`, `current` and `upstream` modes are for those who want \n> to\n> -push out a single branch after finishing work, even when the other\n> -branches are not yet ready to be pushed out. If you are working with\n> -other people to push into the same shared repository, you would want\n> -to use one of these.\n>\n> rebase.stat::\n> Whether to show a diffstat of what changed upstream since the last\n> -- \n> 1.8.3.1.443.g4fd77b9\n>\n> --\nregards\nPhilip\n"},{"id":"221013","messageId":"vpqvc5dj3hy.fsf@anie.imag.fr","threadId":"34163","inReplyTo":"1371377188-18938-1-git-send-email-artagnon@gmail.com","subject":"Re: [PATCH] config doc: rewrite push.default section","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2013-06-16T18:48:41Z","receivedAt":"2013-06-16T18:48:41Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Ramkumar Ramachandra writes:\n\n> +* `current` - push the refspec \"$HEAD\". HEAD is resolved early to a\n> + branch name (referred to as $HEAD). In other words, push the\n> + current branch to update a branch with the same name on the pushing\n> + side.\n\nI'd put it the other way around: the intuitive explanation first, and\nthe technical one after. For people not totally familiar with Git, the\nfirst part does not make much sense (and when I learn a new tool, I\nreally don't like when the doc assumes I already know too much about\nit).\n\nAlso, this $HEAD Vs HEAD doesn't seem very clear to me. I don't have a\nreally good proposal for a better wording, but maybe replacing $HEAD\nwith $branch would make a bit more sense, as having $HEAD != HEAD is\nweird.\n\n> +* `simple` - in central workflows, behaves like `upstream`, except\n> + that it errors out unless branch.$HEAD.merge is equal to $HEAD.\n\nI'd reverse the sentense too. In your wording, I get the feeling that\nerroring out is the normal flow, and pushing is the exception\n(\"unless\").\n\n\"... except that it errors out if branch.$HEAD.merge is not equal to\n$HEAD.\" ?\n\n> + single command. Dangerous, and inappropriate unless you are the\n> + only person updating your push destination.\n\nHere also, I'd have said \"Dangerous, and inappropriate if you are\nnot ...\".\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"221028","messageId":"7vli69iff2.fsf@alter.siamese.dyndns.org","threadId":"34163","inReplyTo":"1371377188-18938-1-git-send-email-artagnon@gmail.com","subject":"Re: [PATCH] config doc: rewrite push.default section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-06-17T03:28:49Z","receivedAt":"2013-06-17T03:28:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramkumar Ramachandra writes:\n\n> Design by Junio.\n\nNot necessary. The conclusion of discussion is a result of\ncollaboration.\n\nThanks for writing it down. It is a good start, but I agree with\nreviews by Philip Oakley and Matthieu Moy we already saw. \n\n - To understand \"if central, works as upstream, otherwise works as\n current\", the readers need to know if their workflow is 'central'\n or not, so we need to say how that is decided upfront (probably\n immediately before \"Possible values are:\" in the introductory\n paragraph for push.default;\n\n - For each of these choices, what it means is more important to the\n readers than how the implementation achieves that semantics\n (e.g. \"current uses refs/heads/foo:refs/heads/foo when you are on\n foo branch\"). I think the ideal is a description of the meaning\n that is clear enough not to require any implementation detail.\n\nI do no think the remainder (snipped) belongs to the log message.\n\nAs this is an attempt to _define_ the semantics of what should\nhappen in triangular workflow, I think it would be healthy to wait\nfor a week or so in order for others (not just two of us) can see if\nwe have defined a sane semantics we would want to go forward with.\nI am reasonably sure 'current' would be the best default for\ntriangular (and that is why I suggested 'simple' to fall back to\nit), but I do not think others had a chance to see what design our\ndiscussion settled, think if that makes sense, and think of a better\nalternative.\n\n> diff --git a/Documentation/config.txt b/Documentation/config.txt\n> index 7fd4035..30350a3 100644\n> --- a/Documentation/config.txt\n> +++ b/Documentation/config.txt\n> @@ -1832,33 +1832,32 @@ push.default::\n> \tline. Possible values are:\n> +\n> --\n> -* `nothing` - do not push anything.\n> -* `matching` - push all branches having the same name in both ends.\n> - This is for those who prepare all the branches into a publishable\n> - shape and then push them out with a single command. It is not\n> - appropriate for pushing into a repository shared by multiple users,\n> - since locally stalled branches will attempt a non-fast forward push\n> - if other users updated the branch.\n> - +\n> - This is currently the default, but Git 2.0 will change the default\n> - to `simple`.\n> -* `upstream` - push the current branch to its upstream branch\n> - (`tracking` is a deprecated synonym for this).\n> - With this, `git push` will update the same remote ref as the one which\n> - is merged by `git pull`, making `push` and `pull` symmetrical.\n> - See \"branch..merge\" for how to configure the upstream branch.\n> -* `simple` - like `upstream`, but refuses to push if the upstream\n> - branch's name is different from the local one. This is the safest\n> - option and is well-suited for beginners. It will become the default\n> - in Git 2.0.\n> -* `current` - push the current branch to a branch of the same name.\n\n> +* `nothing` - error out unless a refspec is explicitly given.\n\nI do not think 'error out' is the primary effect of this mode.\nWouldn't \"do not push anything\" be much better?\n\n> +* `current` - push the refspec \"$HEAD\". HEAD is resolved early to a\n> + branch name (referred to as $HEAD). In other words, push the\n> + current branch to update a branch with the same name on the pushing\n> + side.\n\nAs already pointed out, dropping everything before and including \"In\nother words, \" would be better. Also \"push the current branch\" is\ntalking about the branch on the pushing side (you, the one who is\nrunning \"git push\"), and the side that is getting updated is at the\nreceiving end, not \"pushing side\".\n\n> +* `upstream` - push the refspec \"$HEAD:branch.$HEAD.merge\", and error\n> + out if the push destination is not the same as branch.$HEAD.remote.\n> + The name \"upstream\" refers to the revision \"@{u[pstream]}\" in\n> + linkgit:gitrevisions[7]. It is useful in central workflows, to make\n> + the `push` symmetrical to `pull`.\n> +\n> +* `simple` - in central workflows, behaves like `upstream`, except\n> + that it errors out unless branch.$HEAD.merge is equal to $HEAD. In\n> + non-central workflows, behaves like `current`. It will become the\n> + default in Git 2.0.\n\nI think listing 'simple' at the end would be easier to read. The\nabove already swaps the order to make sure current and upstream are\ndescribed before it, which is good.\n\nBut I do not see a reason to move 'matching' which was next to\n'nothing' here. The \n\n> +* `matching` - push the refspec \":\". In other words, push all\n> + branches having the same name in both ends, even if it means\n> + non-fast-forward updates. This is for those who prepare all the\n> + branches into a publishable shape and then push them out with a\n> + single command. Dangerous, and inappropriate unless you are the\n> + only person updating your push destination.\n\nIt was already pointed out that unnecessary negativity needs to be\nfixed, but more importantly the above \"Dangerous\" is not even\ncorrect.\n\nIf you are \"I am done with this one branch, I want to push it out,\nthe other branches I have touched but they are not yet in a good\nshape to be pushed out\" kind of person, it does not matter if you\nare the only one who is pushing to the destination. You would end\nup pushing out half-baked ones as well if you used 'matching', which\nis not what you want.\n\n> -+\n> -The `simple`, `current` and `upstream` modes are for those who want to\n> -push out a single branch after finishing work, even when the other\n> -branches are not yet ready to be pushed out. If you are working with\n> -other people to push into the same shared repository, you would want\n> -to use one of these.\n\nAnd I do not see a reason to drop this part, especially the first\nsentence.\n"},{"id":"221050","messageId":"vpqip1d803r.fsf@anie.imag.fr","threadId":"34163","inReplyTo":"7vli69iff2.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] config doc: rewrite push.default section","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2013-06-17T11:09:44Z","receivedAt":"2013-06-17T11:09:44Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Junio C Hamano writes:\n\n>> +* `matching` - push the refspec \":\". In other words, push all\n>> + branches having the same name in both ends, even if it means\n>> + non-fast-forward updates. This is for those who prepare all the\n>> + branches into a publishable shape and then push them out with a\n>> + single command. Dangerous, and inappropriate unless you are the\n>> + only person updating your push destination.\n>\n> It was already pointed out that unnecessary negativity needs to be\n> fixed, but more importantly the above \"Dangerous\" is not even\n> correct.\n\nWhat's really dangerous is the --force flag. A few weeks ago I had to\nhelp a colleague who did a \"git push --force\" to update his branch, and\nhe lost data on his co-worker's branches (thanks to \"git reflog\", it\nwasn't an actual data loss, but still pretty bad).\n\nBut then the place to warn loudly is the doc for --force. What about\nthis?\n\n------- 8< ------- 8< ------- 8< ------- 8< ------- 8< ------- 8< \n\n>From a529588dd8df84e54e5ec267068248cc555373f5 Mon Sep 17 00:00:00 2001\nFrom: Matthieu Moy \nDate: Mon, 17 Jun 2013 13:02:39 +0200\nSubject: [PATCH] Documentation/git-push.txt: explain better cases where\n --force is dangerous\n\nThe behavior of \"git push --force\" is rather clear when it updates only\none remote ref, but running it when pushing several branches can really\nbe dangerous. Warn the users a bit more and give them the alternative to\npush only one branch.\n\nSigned-off-by: Matthieu Moy \n---\n Documentation/git-push.txt | 7 +++++++\n 1 file changed, 7 insertions(+)\n\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex 938d1ee..0899a35 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -136,6 +136,13 @@ already exists on the remote side.\n not an ancestor of the local ref used to overwrite it.\n This flag disables the check. This can cause the\n remote repository to lose commits; use it with care.\n+ Note that `--force` applies to all the refs that are pushed,\n+ hence using `git push --all --force`, or `git push --force`\n+ with `push.default` set to `matching` may override refs other\n+ than the current branch (including local refs that are\n+ strictly behind their remote counterpart). To force a push to\n+ only one branch, use `git push +` instead of\n+ `--force`.\n \n --repo=::\n This option is only relevant if no argument is\n-- \n1.8.3.1.495.g13f33cf.dirty\n\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"221063","messageId":"7vsj0ghkqt.fsf@alter.siamese.dyndns.org","threadId":"34163","inReplyTo":"vpqip1d803r.fsf@anie.imag.fr","subject":"Re: [PATCH] config doc: rewrite push.default section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-06-17T14:31:22Z","receivedAt":"2013-06-17T14:31:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matthieu Moy writes:\n\n> But then the place to warn loudly is the doc for --force. What about\n> this?\n\nSounds sensible. I am not sure if \"--all\" is all that common to be\nsingled out, though. \"I always push these out\" refspecs, like\n\n\t[remote \"origin\"]\n \tpush = refs/heads/master\n \tpush = refs/heads/next\n\nshare the need for the same cautiousness against --force, and\n\"applies to all the refs that are pushed\" already covers both.\n\nMentioning 'matching' here is a very good idea, as people may not\nrealize it is pushing out more than the current branch.\n\n> ------- 8< ------- 8< ------- 8< ------- 8< ------- 8< ------- 8< \n>\n> From a529588dd8df84e54e5ec267068248cc555373f5 Mon Sep 17 00:00:00 2001\n> From: Matthieu Moy \n> Date: Mon, 17 Jun 2013 13:02:39 +0200\n> Subject: [PATCH] Documentation/git-push.txt: explain better cases where\n> --force is dangerous\n>\n> The behavior of \"git push --force\" is rather clear when it updates only\n> one remote ref, but running it when pushing several branches can really\n> be dangerous. Warn the users a bit more and give them the alternative to\n> push only one branch.\n>\n> Signed-off-by: Matthieu Moy \n> ---\n> Documentation/git-push.txt | 7 +++++++\n> 1 file changed, 7 insertions(+)\n>\n> diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\n> index 938d1ee..0899a35 100644\n> --- a/Documentation/git-push.txt\n> +++ b/Documentation/git-push.txt\n> @@ -136,6 +136,13 @@ already exists on the remote side.\n> not an ancestor of the local ref used to overwrite it.\n> This flag disables the check. This can cause the\n> remote repository to lose commits; use it with care.\n> + Note that `--force` applies to all the refs that are pushed,\n> + hence using `git push --all --force`, or `git push --force`\n> + with `push.default` set to `matching` may override refs other\n> + than the current branch (including local refs that are\n> + strictly behind their remote counterpart). To force a push to\n> + only one branch, use `git push +` instead of\n> + `--force`.\n> \n> --repo=::\n> This option is only relevant if no argument is\n> -- \n> 1.8.3.1.495.g13f33cf.dirty\n"},{"id":"221075","messageId":"7B6316FB423B45559A4698FD35D519FC@PhilipOakley","threadId":"34163","inReplyTo":"vpqip1d803r.fsf@anie.imag.fr","subject":"Re: [PATCH] config doc: rewrite push.default section","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2013-06-17T17:09:12Z","receivedAt":"2013-06-17T17:09:12Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Matthieu Moy\" \nSent: Monday, June 17, 2013 12:09 PM\n> Junio C Hamano writes:\n>\n>>> +* `matching` - push the refspec \":\". In other words, push all\n>>> + branches having the same name in both ends, even if it means\n>>> + non-fast-forward updates. This is for those who prepare all the\n>>> + branches into a publishable shape and then push them out with a\n>>> + single command. Dangerous, and inappropriate unless you are the\n>>> + only person updating your push destination.\n>>\n>> It was already pointed out that unnecessary negativity needs to be\n>> fixed, but more importantly the above \"Dangerous\" is not even\n>> correct.\n>\n> What's really dangerous is the --force flag. A few weeks ago I had to\n> help a colleague who did a \"git push --force\" to update his branch, \n> and\n> he lost data on his co-worker's branches (thanks to \"git reflog\", it\n> wasn't an actual data loss, but still pretty bad).\n>\n> But then the place to warn loudly is the doc for --force. What about\n> this?\n>\n> ------- 8< ------- 8< ------- 8< ------- 8< ------- 8< ------- 8<\n>\n> From a529588dd8df84e54e5ec267068248cc555373f5 Mon Sep 17 00:00:00 2001\n> From: Matthieu Moy \n> Date: Mon, 17 Jun 2013 13:02:39 +0200\n> Subject: [PATCH] Documentation/git-push.txt: explain better cases \n> where\n> --force is dangerous\n>\n> The behavior of \"git push --force\" is rather clear when it updates \n> only\n> one remote ref, but running it when pushing several branches can \n> really\n> be dangerous. Warn the users a bit more and give them the alternative \n> to\n> push only one branch.\n>\n> Signed-off-by: Matthieu Moy \n> ---\n> Documentation/git-push.txt | 7 +++++++\n> 1 file changed, 7 insertions(+)\n>\n> diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\n> index 938d1ee..0899a35 100644\n> --- a/Documentation/git-push.txt\n> +++ b/Documentation/git-push.txt\n> @@ -136,6 +136,13 @@ already exists on the remote side.\n> not an ancestor of the local ref used to overwrite it.\n> This flag disables the check. This can cause the\n> remote repository to lose commits; use it with care.\n> + Note that `--force` applies to all the refs that are pushed,\n> + hence using `git push --all --force`, or `git push --force`\n> + with `push.default` set to `matching` may override refs other\n> + than the current branch (including local refs that are\n> + strictly behind their remote counterpart). To force a push to\n> + only one branch, use `git push +` instead of\n> + `--force`.\n\nIt would be useful to include a real example \"e.g. `git push origin \n+master`\", or a link to specifying a refspec \"see ... above\", \nsuch that the \"+\" doesn't get lost in the general text, as push is one \nof the first few commands a new user is likely to be looking up (and \nmisunderstanding ;-), so let's make the + obvious\n\nI did notice that the ... section doesn't actually associate \nthe \"+\" with the force action - Am I misunderstanding this?\n\n>\n> --repo=::\n> This option is only relevant if no argument is\n> -- \n> 1.8.3.1.495.g13f33cf.dirty\n>\n>\n> -- \n> Matthieu Moy\n> http://www-verimag.imag.fr/~moy/\n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at http://vger.kernel.org/majordomo-info.html\n>\n>\n> -----\n> No virus found in this message.\n> Checked by AVG - www.avg.com\n> Version: 2013.0.3345 / Virus Database: 3199/6417 - Release Date: \n> 06/16/13\n> \n"},{"id":"221077","messageId":"vpq61xc1wnd.fsf@anie.imag.fr","threadId":"34163","inReplyTo":"7B6316FB423B45559A4698FD35D519FC@PhilipOakley","subject":"Re: [PATCH] config doc: rewrite push.default section","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2013-06-17T17:20:54Z","receivedAt":"2013-06-17T17:20:54Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"\"Philip Oakley\" writes:\n\n>> + Note that `--force` applies to all the refs that are pushed,\n>> + hence using `git push --all --force`, or `git push --force`\n>> + with `push.default` set to `matching` may override refs other\n>> + than the current branch (including local refs that are\n>> + strictly behind their remote counterpart). To force a push to\n>> + only one branch, use `git push +` instead of\n>> + `--force`.\n>\n> It would be useful to include a real example \"e.g. `git push origin\n> +master`\", or a link to specifying a refspec \"see ... above\",\n> such that the \"+\" doesn't get lost in the general text, as push is one\n> of the first few commands a new user is likely to be looking up (and\n> misunderstanding ;-), so let's make the + obvious\n\nYes, why not. I'll point to the section for detail, and just\ngive an example here.\n\n> I did notice that the ... section doesn't actually associate\n> the \"+\" with the force action - Am I misunderstanding this?\n\nIt says:\n\n By having the optional leading `+`, you can tell Git to update the\n ref even if it is not allowed by default (e.g., it is not a\n fast-forward.)\"\n\nI think it's OK.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"221083","messageId":"F2D994ABCB8442B5A3F71791BAFB7C80@PhilipOakley","threadId":"34163","inReplyTo":"vpq61xc1wnd.fsf@anie.imag.fr","subject":"Re: [PATCH] config doc: rewrite push.default section","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2013-06-17T18:10:27Z","receivedAt":"2013-06-17T18:10:27Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Matthieu Moy\" \nSent: Monday, June 17, 2013 6:20 PM\n> \"Philip Oakley\" writes:\n>\n>>> + Note that `--force` applies to all the refs that are pushed,\n>>> + hence using `git push --all --force`, or `git push --force`\n>>> + with `push.default` set to `matching` may override refs \n>>> other\n>>> + than the current branch (including local refs that are\n>>> + strictly behind their remote counterpart). To force a push \n>>> to\n>>> + only one branch, use `git push +` instead \n>>> of\n>>> + `--force`.\n>>\n>> It would be useful to include a real example \"e.g. `git push origin\n>> +master`\", or a link to specifying a refspec \"see ... \n>> above\",\n>> such that the \"+\" doesn't get lost in the general text, as push is \n>> one\n>> of the first few commands a new user is likely to be looking up (and\n>> misunderstanding ;-), so let's make the + obvious\n>\n> Yes, why not. I'll point to the section for detail, and just\n> give an example here.\n>\n>> I did notice that the ... section doesn't actually associate\n>> the \"+\" with the force action - Am I misunderstanding this?\n>\n> It says:\n>\n> By having the optional leading `+`, you can tell Git to update the\n> ref even if it is not allowed by default (e.g., it is not a\n> fast-forward.)\"\n>\n> I think it's OK.\n\nI was more noting that there is zero direct association in the text \nbetween the --force option, and the \"+\", and with that, a funny feeling \nthat either (a) they had subtle differences I hadn't understood, or (b) \nthey were exactly the same and the documenation was being too subtle and \na cluebat should be applied to the documenation (on the principle I am \nnot a unique fool ;-)\n\n>\n> -- \n> Matthieu Moy\n> http://www-verimag.imag.fr/~moy/\n\nMaybe...\n------- 8< ------- \nFrom 57d8aaac6b7543919aaf09909c13a180722c0a94 Mon Sep 17 00:00:00 2001\nFrom: Philip Oakley \nDate: Mon, 17 Jun 2013 18:47:04 +0100\nSubject: [PATCH] git-push doc: + refspec is --force\n\nSigned-off-by: Philip Oakley \n---\n Documentation/git-push.txt | 2 ++\n 1 file changed, 2 insertions(+)\n\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex eb2883c..df92b09 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -136,6 +136,8 @@ already exists on the remote side.\n not an ancestor of the local ref used to overwrite it.\n This flag disables the check. This can cause the\n remote repository to lose commits; use it with care.\n+ See also the optional leading `+` ref specifier in\n+ '...' above.\n\n --repo=::\n This option is only relevant if no argument is\n-- \n1.8.1.msysgit.1\n"},{"id":"221153","messageId":"CALkWK0nn9Mym7sOLrLooHc5ieh_4PVZv445GDqVkmKUcHB0yew@mail.gmail.com","threadId":"34163","inReplyTo":"89027CD773CE4BFC8C293D2454CE4AE5@PhilipOakley","subject":"Re: [PATCH] config doc: rewrite push.default section","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-06-18T07:08:45Z","receivedAt":"2013-06-18T07:08:45Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Philip Oakley wrote:\n> A sentence, in the Documentation/config.txt, is needed to clarify the\n> Central workflow and any distinction with the non-central workflow(s). We\n> cannot assume the new reader has the same world view of that concept (they\n> may be thinking it means we do a centralised VCS, not a DVCS with a chosen\n> central primary repo - assuming I have understood it correctly).\n>\n> It took a while to bottom out the issues, so it is worth summarising the key\n> point(s) in the documentation to avoid having to repeat the disussions ;-)\n\nI'm not sure where to put it: Documentation/gitworkflows.txt perhaps?\n\n> [...]\n\nAgreed with the rest. Thanks.\n"},{"id":"221157","messageId":"CALkWK0ng+NOLNFJ8soccx-bLQtiV8c_zaLp4kJUh7NEBWAKFvg@mail.gmail.com","threadId":"34163","inReplyTo":"7vli69iff2.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] config doc: rewrite push.default section","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-06-18T07:39:51Z","receivedAt":"2013-06-18T07:39:51Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Junio C Hamano wrote:\n> I do no think the remainder (snipped) belongs to the log message.\n\nOh, it was never intended to be a proper commit message. I'll write a\nproper one when I send it in with the implementation.\n\n> - To understand \"if central, works as upstream, otherwise works as\n> current\", the readers need to know if their workflow is 'central'\n> or not, so we need to say how that is decided upfront (probably\n> immediately before \"Possible values are:\" in the introductory\n> paragraph for push.default;\n\nGood idea.\n\n> - For each of these choices, what it means is more important to the\n> readers than how the implementation achieves that semantics\n> (e.g. \"current uses refs/heads/foo:refs/heads/foo when you are on\n> foo branch\"). I think the ideal is a description of the meaning\n> that is clear enough not to require any implementation detail.\n\nI'd definitely like to include the push refspec, to educate users on\nhow to achieve a one-off matching-push even when push.default is set\nto current, for example.\n\n> As this is an attempt to _define_ the semantics of what should\n> happen in triangular workflow, I think it would be healthy to wait\n> for a week or so in order for others (not just two of us) can see if\n> we have defined a sane semantics we would want to go forward with.\n\nAgreed.\n\n> I am reasonably sure 'current' would be the best default for\n> triangular (and that is why I suggested 'simple' to fall back to\n> it), but I do not think others had a chance to see what design our\n> discussion settled, think if that makes sense, and think of a better\n> alternative.\n\nYou didn't realize one thing, because my wording was terrible:\n`simple` is just a \"safe\" version of `current` :)\n\n* `simple` - behaves exactly like `current`, with one safety feature:\nin central workflows, it errors out if branch.$branch.merge is set and\nis not equal to $branch (to make sure that the `push` and `pull`\naren't asymmetrical).\n\nIn other words, it's `current` with the safety feature of `upstream`.\nThere's no point in erroring out if no upstream is set, or mentioning\nits relationship with `upstream`.\n\n>> +* `nothing` - error out unless a refspec is explicitly given.\n>\n> I do not think 'error out' is the primary effect of this mode.\n> Wouldn't \"do not push anything\" be much better?\n\n\"Do not push anything\" is misleading because it implies an exit status\nof zero; what is really does is \"error out\", no?\n\n>> +* `current` - push the refspec \"$HEAD\". HEAD is resolved early to a\n>> + branch name (referred to as $HEAD). In other words, push the\n>> + current branch to update a branch with the same name on the pushing\n>> + side.\n>\n> As already pointed out, dropping everything before and including \"In\n> other words, \" would be better.\n\nI'd like to put it in the end, like Matthieu suggested.\n\n> Also \"push the current branch\" is\n> talking about the branch on the pushing side (you, the one who is\n> running \"git push\"), and the side that is getting updated is at the\n> receiving end, not \"pushing side\".\n\n\"receiving end\" is better, yes.\n\n> I think listing 'simple' at the end would be easier to read. The\n> above already swaps the order to make sure current and upstream are\n> described before it, which is good.\n\nAs I pointed out, `simple` is just a composition of `current` and\n`upstream`. That's why it comes after them. Also, I thought\n`nothing`, `current`, `upstream` were fundamental: which is why they\ncome first.\n\n> But I do not see a reason to move 'matching' which was next to\n> 'nothing' here.\n\nIt's probably a personal bias, but I don't like matching at all :P\n\n>> +* `matching` - push the refspec \":\". In other words, push all\n>> + branches having the same name in both ends, even if it means\n>> + non-fast-forward updates. This is for those who prepare all the\n>> + branches into a publishable shape and then push them out with a\n>> + single command. Dangerous, and inappropriate unless you are the\n>> + only person updating your push destination.\n>\n> It was already pointed out that unnecessary negativity needs to be\n> fixed, but more importantly the above \"Dangerous\" is not even\n> correct.\n\nOkay, I'll explain my bias:\n\nI have _never_ lost data with git: the reflog is my close companion.\nThere is one recent instance where I *lost* data, and I was very\nunhappy about it. I work on multiple machines, and not all local\nbranches are always synced with the upstream branches: when I switch\nto a local branch to work on the topic, I notice my prompt and get it\nto '=' before starting work. In this one instance, I was developing\n@{push} and toying around with various push.default settings. I'd\nforgotten that I'd set push.default to matching and issued my usual\npush to update my branch. This resulted in a huge number of my\nbranches getting rewound, and I could do nothing about it!\n\nWe've mentioned that pull --rebase is _dangerous_ (with the underline\nfor effect) in our documentation, when it's trivial to recover from\nit: git reset --hard @{1}. Yet, when I mention matching being\ndangerous, I'm accused of being unnecessarily negative :\\\n\nIn my opinion, `matching` is a bad and unpredictable setting, and\ndeserves last place on the list. `nothing` deserves first place,\nbecause it is the most predictable and least surprising. Do not\nmistake my stance for \"matching is not useful\"; ofcourse it is useful,\nand I sometimes use it myself using \":\" explicitly.\n\n>> -+\n>> -The `simple`, `current` and `upstream` modes are for those who want to\n>> -push out a single branch after finishing work, even when the other\n>> -branches are not yet ready to be pushed out. If you are working with\n>> -other people to push into the same shared repository, you would want\n>> -to use one of these.\n>\n> And I do not see a reason to drop this part, especially the first\n> sentence.\n\nI thought we should make it clear in the `matching` section; after\nall, it's just `matching` versus everything else.\n"},{"id":"221159","messageId":"CALkWK0mOsSskGE2ukS4M8QN_Nuf7+rVosWG6E81QXgoQO8Zz-Q@mail.gmail.com","threadId":"34163","inReplyTo":"vpqvc5dj3hy.fsf@anie.imag.fr","subject":"Re: [PATCH] config doc: rewrite push.default section","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-06-18T07:47:09Z","receivedAt":"2013-06-18T07:47:09Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Matthieu Moy wrote:\n> I'd put it the other way around: the intuitive explanation first, and\n> the technical one after. For people not totally familiar with Git, the\n> first part does not make much sense (and when I learn a new tool, I\n> really don't like when the doc assumes I already know too much about\n> it).\n\nGood.\n\n> Also, this $HEAD Vs HEAD doesn't seem very clear to me. I don't have a\n> really good proposal for a better wording, but maybe replacing $HEAD\n> with $branch would make a bit more sense, as having $HEAD != HEAD is\n> weird.\n\nGood.\n\n>> +* `simple` - in central workflows, behaves like `upstream`, except\n>> + that it errors out unless branch.$HEAD.merge is equal to $HEAD.\n>\n> \"... except that it errors out if branch.$HEAD.merge is not equal to\n> $HEAD.\" ?\n\nGood.\n\n>> + single command. Dangerous, and inappropriate unless you are the\n>> + only person updating your push destination.\n>\n> Here also, I'd have said \"Dangerous, and inappropriate if you are\n> not ...\".\n\nI might have overplayed the danger a bit, as Junio points out. I'll\nhave a look at your --force documentation patch.\n"}]}