Re: [PATCH] Documentation/git-push.txt: explain better cases where --force is dangerous

Marc Branchaud [off-list ref] writes:

On 13-06-17 01:52 PM, Matthieu Moy wrote:

quoted

The behavior of "git push --force" is rather clear when it updates only
one remote ref, but running it when pushing several branches can really
be dangerous. Warn the users a bit more and give them the alternative to
push only one branch.

Signed-off-by: Matthieu Moy <redacted>
---
  Documentation/git-push.txt | 8 ++++++++
  1 file changed, 8 insertions(+)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 938d1ee..9b9e7d1 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt

@@ -136,6 +136,14 @@ already exists on the remote side.
  	not an ancestor of the local ref used to overwrite it.
  	This flag disables the check.  This can cause the
  	remote repository to lose commits; use it with care.
+	Note that `--force` applies to all the refs that are pushed,
+	hence using it with `push.default` set to `matching` or with
+	multiple push destination configured may override refs other

s/destination/destinations/

Good eyes.

After I re-read the one, I found that "override" somewhat a strange
expression.  There is nothing that overrides or to be overriden.

How about putting it like this?

 Documentation/git-push.txt | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 8b637d3..21294aa 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt

@@ -124,6 +124,15 @@ no `push.default` configuration variable is set.
 	not an ancestor of the local ref used to overwrite it.
 	This flag disables the check.  This can cause the
 	remote repository to lose commits; use it with care.
+	Note that `--force` applies to all the refs that are pushed,
+	hence using it with `push.default` set to `matching` or with
+	multiple push destinations configured with `remote.*.push`
+	may push out refs other than the current branch (including
+	local refs that are strictly behind their remote counterpart).
+	To force a push to only one branch, use a `+` in front of the
+	refspec to push	(e.g `git push origin +master` to force a push
+	to the `master`	branch). See the `<refspec>...` section above
+	for details.
 
 --repo=<repository>::
 	This option is only relevant if no <repository> argument is