git-sh-setup: make require_clean_work_tree part of the interface

92c62a3 (Porcelain scripts: Rewrite cryptic "needs update" error
message, 2010-10-19) refactored git's own checking to a function in
git-sh-setup.  This is a very useful thing for script writers, so
document it.

Signed-off-by: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt
index 3da241304b0d2fdaa376bca740beb024a36b2cb6..76856633a15b958a159de371ca2e0a9e0fbfcdba 100644 (file)
--- a/Documentation/git-sh-setup.txt
+++ b/Documentation/git-sh-setup.txt
@@ -62,6 +62,16 @@ require_work_tree::
        if so.  Used by scripts that require working tree
        (e.g. `checkout`).
 
+require_clean_work_tree <action> [<hint>]::
+       checks that the working tree and index associated with the
+       repository have no uncommitted changes to tracked files.
+       Otherwise it emits an error message of the form `Cannot
+       <action>: <reason>. <hint>`, and dies.  Example:
++
+----------------
+require_clean_work_tree rebase "Please commit or stash them."
+----------------
+
 get_author_ident_from_commit::
        outputs code for use with eval to set the GIT_AUTHOR_NAME,
        GIT_AUTHOR_EMAIL and GIT_AUTHOR_DATE variables for a given commit.