patch, 2 partsgit-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>
---

Noticed while helping ribasushi on IRC.

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

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 <trast@student.ethz.ch>
---
 Documentation/git-sh-setup.txt |   11 ++++-------
 1 files changed, 4 insertions(+), 7 deletions(-)

Thomas Rast <trast@student.ethz.ch> writes:

You would need to say what that IRC user needed to find out. Depending on that, letting the user know that there is no point reading on early and not waste his or her time may be a good thing. That was what the paragraph was designed for. IOW, it is not to "scare" away, but to allow the users to decide if they are intended audiences.

The reworded version does avoid sounding scary, but loses the "this document is for people who want to write new or understand existing Porcelain scripts", which is a documentation regression.

On Tue, Dec 20, 2011 at 12:09, Thomas Rast <trast@student.ethz.ch> wrote:

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.

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

Junio C Hamano writes:

Well, the original question was [*]

  <ribasushi> how do I write a batch-test (goes in a script, exit value matters only) to test if the current workdir is clean?
  <ribasushi> i.e. nothing staged/unstaged to commit
  <shruggar> last I looked, there was no "all in one" method :/
  <shruggar> git diff -q && git diff —cached -q, perhaps
  <charon> ribasushi: . "$(git --exec-path)/git-sh-setup" ; require_clean_worktree
  <shruggar> but I think that's ignoring something
  <ribasushi> lack of output of `git status -s` seems to be what I want
  <ribasushi> hmmm
  <ribasushi> charon: git-gh-setup's manpage does not seem to list what you gave me
  <ribasushi> and the manpage says that I should not be touching it...

Leaving aside my worktree vs. work_tree mistake, he concluded that he should not be using it even though he is a script writer.

Regardless, I don't really care enough about this one; let's just do the first patch (v2 upcoming) so that we have documentation to point people at.

[*] http://colabti.org/irclogger/irclogger_log/git?date=2011-12-20#l1284

Thomas Rast <trast@student.ethz.ch> writes:

Can we avoid explaining "clean" with the same word "clean", which adds no new information? IOW, what does "clean" mean in the context of this helper shell function? No untracked cruft? No un-added changes? What are the kind of dirtiness being checked?

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>
---
 Documentation/git-sh-setup.txt |   10 ++++++++++
 1 files changed, 10 insertions(+), 0 deletions(-)

Thomas Rast <trast@student.ethz.ch> writes:

Doesn't it also enforce cleanliness on the index, not just the working tree?

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>
---

Junio C Hamano writes:

Of course.  Here's the "and index" update.

BTW neither gitglossary(7) nor git-cherry-pick(1) get this right.

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

Thanks, will queue.