[PATCH 1/2] 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 <redacted>
---

Noticed while helping ribasushi on IRC.

 Documentation/git-sh-setup.txt |    9 +++++++++
 1 files changed, 9 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt
index a2f346c..bbfefca 100644
--- a/Documentation/git-sh-setup.txt
+++ b/Documentation/git-sh-setup.txt

@@ -68,6 +68,15 @@ require_work_tree_exists::
 	cd_to_toplevel, which is impossible to do if there is no
 	working tree.
 
+require_clean_work_tree <action> [<hint>]::
+	checks if the working tree associated with the repository is
+	clean.  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.

-- 
1.7.8.484.gdad4270

At least one IRC user was scared away by the introductory "This is not
a command the end user would want to run.  Ever." to the point of not
reading on.

Reword it in a more matter-of-fact way that does not intentionally try
to scare the user away.  Since 46bac90 (Do not install shell libraries
executable, 2010-01-31) it is not executable anyway, so the end user
would get

  $ git sh-setup
  fatal: cannot exec 'git-sh-setup': Permission denied

Signed-off-by: Thomas Rast <redacted>
---
 Documentation/git-sh-setup.txt |   11 ++++-------
 1 files changed, 4 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt
index bbfefca..612fb50 100644
--- a/Documentation/git-sh-setup.txt
+++ b/Documentation/git-sh-setup.txt

@@ -13,13 +13,10 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-This is not a command the end user would want to run.  Ever.
-This documentation is meant for people who are studying the
-Porcelain-ish scripts and/or are writing new ones.
-
-The 'git sh-setup' scriptlet is designed to be sourced (using
-`.`) by other shell scripts to set up some variables pointing at
-the normal git directories and a few helper shell functions.
+This command cannot be run by the end user.  Shell scripts can
+source it (using `.` as indicated above) to set up some variables
+pointing at the normal git directories and a few helper shell
+functions.
 
 Before sourcing it, your script should set up a few variables;
 `USAGE` (and `LONG_USAGE`, if any) is used to define message

-- 
1.7.8.484.gdad4270

On Tue, Dec 20, 2011 at 12:09, Thomas Rast [off-list ref] wrote:

At least one IRC user was scared away by the introductory "This is not
a command the end user would want to run.  Ever." to the point of not
reading on.

Arguably that's the point isn't it? To not have people who aren't
maintaining Git itself waste time on reading it.

Anyway I don't care how it's worded, but if you're going to patch it
you should probably do these too for consistency, since they
copy/paste this same blurb:

    $ git --no-pager grep -l 'This is not a command the end user would
want to run.  Ever.'
    Documentation/git-mergetool--lib.txt
    Documentation/git-sh-i18n--envsubst.txt
    Documentation/git-sh-i18n.txt
    Documentation/git-sh-setup.txt

And actually we might want to do all those with some asciidoc include
mechanism.