[PATCH 7/7] push: document --lockref

[Junio C Hamano <gitster@pobox.com>]

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-push.txt | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index f7dfe48..e7c8bd6 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -11,6 +11,7 @@ SYNOPSIS
 [verse]
 'git push' [--all | --mirror | --tags] [--follow-tags] [-n | --dry-run] [--receive-pack=<git-receive-pack>]
 	   [--repo=<repository>] [-f | --force] [--prune] [-v | --verbose] [-u | --set-upstream]
+	   [--lockref[=<refname>[:[<expect>]]]]
 	   [--no-verify] [<repository> [<refspec>...]]
 
 DESCRIPTION
@@ -146,6 +147,31 @@ already exists on the remote side.
 	to the `master`	branch). See the `<refspec>...` section above
 	for details.
 
+--lockref::
+--lockref=<refname>::
+--lockref=<refname>:<expect>::
+	When updating <refname> at the remote, make sure that the
+	ref currently points at <expect> (an object name), and else
+	fail the push, even if `--force` is specified.  If only
+	<refname> is given, the expected value is taken from the
+	remote-tracking branch that holds the last-observed value of
+	the <refname>.  <expect> given as an empty string means the
+	<refname> should not exist and this push must be creating
+	it.  If `--lockref` (without any value) is given, make sure
+	each ref this push is going to update points at the object
+	our remote-tracking branch for it points at.
++
+This is meant to make `--force` safer to use.  Imagine that you have
+to rebase what you have already published.  You will have to
+`--force` the push to replace the history you originally published
+with the rebased history.  If somebody else built on top of your
+original history while you are rebasing, the tip of the branch at
+the remote may advance with her commit, and blindly pushing with
+`--force` will lose her work.  By using this option to specify that
+you expect the history you are updating is what you rebased and want
+to replace, you can make sure other people's work will not be losed
+by a forced push. in such a case.
+
 --repo=<repository>::
 	This option is only relevant if no <repository> argument is
 	passed in the invocation. In this case, 'git push' derives the
-- 
1.8.3.2-875-g76c723c