{"thread":{"id":"29211","subject":"[PATCH 1/2] git-sh-setup: make require_clean_work_tree part of the interface","startedAt":"2011-12-20T11:09:04Z","lastAt":"2011-12-20T22:05:54Z","messageCount":10,"participants":["Thomas Rast","Junio C Hamano","Ævar Arnfjörð Bjarmason"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"181522","messageId":"c53feb0de8006c205fd26c2c07dcd78bd86b6c24.1324378986.git.trast@student.ethz.ch","threadId":"29211","inReplyTo":null,"subject":"[PATCH 1/2] git-sh-setup: make require_clean_work_tree part of the interface","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2011-12-20T11:09:04Z","receivedAt":"2011-12-20T11:09:04Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"92c62a3 (Porcelain scripts: Rewrite cryptic \"needs update\" error\nmessage, 2010-10-19) refactored git's own checking to a function in\ngit-sh-setup. This is a very useful thing for script writers, so\ndocument it.\n\nSigned-off-by: Thomas Rast \n---\n\nNoticed while helping ribasushi on IRC.\n\n Documentation/git-sh-setup.txt | 9 +++++++++\n 1 files changed, 9 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt\nindex a2f346c..bbfefca 100644\n--- a/Documentation/git-sh-setup.txt\n+++ b/Documentation/git-sh-setup.txt\n@@ -68,6 +68,15 @@ require_work_tree_exists::\n \tcd_to_toplevel, which is impossible to do if there is no\n \tworking tree.\n \n+require_clean_work_tree []::\n+\tchecks if the working tree associated with the repository is\n+\tclean. Otherwise it emits an error message of the form\n+\t`Cannot : . `, and dies. Example:\n++\n+----------------\n+require_clean_work_tree rebase \"Please commit or stash them.\"\n+----------------\n+\n get_author_ident_from_commit::\n \toutputs code for use with eval to set the GIT_AUTHOR_NAME,\n \tGIT_AUTHOR_EMAIL and GIT_AUTHOR_DATE variables for a given commit.\n-- \n1.7.8.484.gdad4270\n"},{"id":"181523","messageId":"c8867738c264a76f9662080b64e00615ec1aa28f.1324378986.git.trast@student.ethz.ch","threadId":"29211","inReplyTo":"c53feb0de8006c205fd26c2c07dcd78bd86b6c24.1324378986.git.trast@student.ethz.ch","subject":"[PATCH 2/2] Documentation: make git-sh-setup docs less scary","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2011-12-20T11:09:05Z","receivedAt":"2011-12-20T11:09:05Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"At least one IRC user was scared away by the introductory \"This is not\na command the end user would want to run. Ever.\" to the point of not\nreading on.\n\nReword it in a more matter-of-fact way that does not intentionally try\nto scare the user away. Since 46bac90 (Do not install shell libraries\nexecutable, 2010-01-31) it is not executable anyway, so the end user\nwould get\n\n $ git sh-setup\n fatal: cannot exec 'git-sh-setup': Permission denied\n\nSigned-off-by: Thomas Rast \n---\n Documentation/git-sh-setup.txt | 11 ++++-------\n 1 files changed, 4 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt\nindex bbfefca..612fb50 100644\n--- a/Documentation/git-sh-setup.txt\n+++ b/Documentation/git-sh-setup.txt\n@@ -13,13 +13,10 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-This is not a command the end user would want to run. Ever.\n-This documentation is meant for people who are studying the\n-Porcelain-ish scripts and/or are writing new ones.\n-\n-The 'git sh-setup' scriptlet is designed to be sourced (using\n-`.`) by other shell scripts to set up some variables pointing at\n-the normal git directories and a few helper shell functions.\n+This command cannot be run by the end user. Shell scripts can\n+source it (using `.` as indicated above) to set up some variables\n+pointing at the normal git directories and a few helper shell\n+functions.\n \n Before sourcing it, your script should set up a few variables;\n `USAGE` (and `LONG_USAGE`, if any) is used to define message\n-- \n1.7.8.484.gdad4270\n"},{"id":"181528","messageId":"7v1urzkq2i.fsf@alter.siamese.dyndns.org","threadId":"29211","inReplyTo":"c8867738c264a76f9662080b64e00615ec1aa28f.1324378986.git.trast@student.ethz.ch","subject":"Re: [PATCH 2/2] Documentation: make git-sh-setup docs less scary","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-12-20T19:20:37Z","receivedAt":"2011-12-20T19:20:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Thomas Rast writes:\n\n> At least one IRC user was scared away by the introductory \"This is not\n> a command the end user would want to run. Ever.\" to the point of not\n> reading on.\n\nYou would need to say what that IRC user needed to find out. Depending on\nthat, letting the user know that there is no point reading on early and\nnot waste his or her time may be a good thing. That was what the paragraph\nwas designed for. IOW, it is not to \"scare\" away, but to allow the users\nto decide if they are intended audiences.\n\nThe reworded version does avoid sounding scary, but loses the \"this\ndocument is for people who want to write new or understand existing\nPorcelain scripts\", which is a documentation regression.\n\n> Reword it in a more matter-of-fact way that does not intentionally try\n> to scare the user away. Since 46bac90 (Do not install shell libraries\n> executable, 2010-01-31) it is not executable anyway, so the end user\n> would get\n>\n> $ git sh-setup\n> fatal: cannot exec 'git-sh-setup': Permission denied\n>\n> Signed-off-by: Thomas Rast \n> ---\n> Documentation/git-sh-setup.txt | 11 ++++-------\n> 1 files changed, 4 insertions(+), 7 deletions(-)\n>\n> diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt\n> index bbfefca..612fb50 100644\n> --- a/Documentation/git-sh-setup.txt\n> +++ b/Documentation/git-sh-setup.txt\n> @@ -13,13 +13,10 @@ SYNOPSIS\n> DESCRIPTION\n> -----------\n> \n> -This is not a command the end user would want to run. Ever.\n> -This documentation is meant for people who are studying the\n> -Porcelain-ish scripts and/or are writing new ones.\n> -\n> -The 'git sh-setup' scriptlet is designed to be sourced (using\n> -`.`) by other shell scripts to set up some variables pointing at\n> -the normal git directories and a few helper shell functions.\n> +This command cannot be run by the end user. Shell scripts can\n> +source it (using `.` as indicated above) to set up some variables\n> +pointing at the normal git directories and a few helper shell\n> +functions.\n> \n> Before sourcing it, your script should set up a few variables;\n> `USAGE` (and `LONG_USAGE`, if any) is used to define message\n"},{"id":"181529","messageId":"7vwr9rjbaq.fsf@alter.siamese.dyndns.org","threadId":"29211","inReplyTo":"c53feb0de8006c205fd26c2c07dcd78bd86b6c24.1324378986.git.trast@student.ethz.ch","subject":"Re: [PATCH 1/2] git-sh-setup: make require_clean_work_tree part of the interface","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-12-20T19:25:01Z","receivedAt":"2011-12-20T19:25:01Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Thomas Rast writes:\n\n> 92c62a3 (Porcelain scripts: Rewrite cryptic \"needs update\" error\n> message, 2010-10-19) refactored git's own checking to a function in\n> git-sh-setup. This is a very useful thing for script writers, so\n> document it.\n\nCan we avoid explaining \"clean\" with the same word \"clean\", which adds no\nnew information? IOW, what does \"clean\" mean in the context of this helper\nshell function? No untracked cruft? No un-added changes? What are the kind\nof dirtiness being checked?\n\n> +require_clean_work_tree []::\n> +\tchecks if the working tree associated with the repository is\n> +\tclean. Otherwise it emits an error message of the form\n> +\t`Cannot : . `, and dies. Example:\n> ++\n> +----------------\n> +require_clean_work_tree rebase \"Please commit or stash them.\"\n> +----------------\n> +\n> get_author_ident_from_commit::\n> \toutputs code for use with eval to set the GIT_AUTHOR_NAME,\n> \tGIT_AUTHOR_EMAIL and GIT_AUTHOR_DATE variables for a given commit.\n"},{"id":"181531","messageId":"CACBZZX5BSfh8S9Kf1Wbi+NPEKpxJNXU8TD8-hkC2o1Mi91Or6A@mail.gmail.com","threadId":"29211","inReplyTo":"c8867738c264a76f9662080b64e00615ec1aa28f.1324378986.git.trast@student.ethz.ch","subject":"Re: [PATCH 2/2] Documentation: make git-sh-setup docs less scary","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2011-12-20T19:45:05Z","receivedAt":"2011-12-20T19:45:05Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Tue, Dec 20, 2011 at 12:09, Thomas Rast wrote:\n> At least one IRC user was scared away by the introductory \"This is not\n> a command the end user would want to run.  Ever.\" to the point of not\n> reading on.\n\nArguably that's the point isn't it? To not have people who aren't\nmaintaining Git itself waste time on reading it.\n\nAnyway I don't care how it's worded, but if you're going to patch it\nyou should probably do these too for consistency, since they\ncopy/paste this same blurb:\n\n $ git --no-pager grep -l 'This is not a command the end user would\nwant to run. Ever.'\n Documentation/git-mergetool--lib.txt\n Documentation/git-sh-i18n--envsubst.txt\n Documentation/git-sh-i18n.txt\n Documentation/git-sh-setup.txt\n\nAnd actually we might want to do all those with some asciidoc include\nmechanism.\n"},{"id":"181535","messageId":"87bor3ounz.fsf@thomas.inf.ethz.ch","threadId":"29211","inReplyTo":"CACBZZX5BSfh8S9Kf1Wbi+NPEKpxJNXU8TD8-hkC2o1Mi91Or6A@mail.gmail.com","subject":"Re: [PATCH 2/2] Documentation: make git-sh-setup docs less scary","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2011-12-20T20:27:44Z","receivedAt":"2011-12-20T20:27:44Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n> On Tue, Dec 20, 2011 at 12:09, Thomas Rast wrote:\n>> At least one IRC user was scared away by the introductory \"This is not\n>> a command the end user would want to run.  Ever.\" to the point of not\n>> reading on.\n>\n> Arguably that's the point isn't it? To not have people who aren't\n> maintaining Git itself waste time on reading it.\n\nJunio C Hamano writes:\n> You would need to say what that IRC user needed to find out. Depending on\n> that, letting the user know that there is no point reading on early and\n> not waste his or her time may be a good thing. That was what the paragraph\n> was designed for. IOW, it is not to \"scare\" away, but to allow the users\n> to decide if they are intended audiences.\n\nWell, the original question was [*]\n\n how do I write a batch-test (goes in a script, exit value matters only) to test if the current workdir is clean?\n i.e. nothing staged/unstaged to commit\n last I looked, there was no \"all in one\" method :/\n git diff -q && git diff —cached -q, perhaps\n ribasushi: . \"$(git --exec-path)/git-sh-setup\" ; require_clean_worktree\n but I think that's ignoring something\n lack of output of `git status -s` seems to be what I want\n hmmm\n charon: git-gh-setup's manpage does not seem to list what you gave me\n and the manpage says that I should not be touching it...\n\nLeaving aside my worktree vs. work_tree mistake, he concluded that he\nshould not be using it even though he is a script writer.\n\nRegardless, I don't really care enough about this one; let's just do the\nfirst patch (v2 upcoming) so that we have documentation to point people\nat.\n\n\n[*] http://colabti.org/irclogger/irclogger_log/git?date=2011-12-20#l1284\n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"181536","messageId":"23d761193dcf25f36206adc3d392e8578c566cd7.1324412815.git.trast@student.ethz.ch","threadId":"29211","inReplyTo":"7vwr9rjbaq.fsf@alter.siamese.dyndns.org","subject":"[PATCH v2] git-sh-setup: make require_clean_work_tree part of the interface","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2011-12-20T20:29:54Z","receivedAt":"2011-12-20T20:29:54Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"92c62a3 (Porcelain scripts: Rewrite cryptic \"needs update\" error\nmessage, 2010-10-19) refactored git's own checking to a function in\ngit-sh-setup. This is a very useful thing for script writers, so\ndocument it.\n\nSigned-off-by: Thomas Rast \n---\n Documentation/git-sh-setup.txt | 10 ++++++++++\n 1 files changed, 10 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt\nindex a2f346c..9a0e574 100644\n--- a/Documentation/git-sh-setup.txt\n+++ b/Documentation/git-sh-setup.txt\n@@ -68,6 +68,16 @@ require_work_tree_exists::\n \tcd_to_toplevel, which is impossible to do if there is no\n \tworking tree.\n \n+require_clean_work_tree []::\n+\tchecks that the working tree associated with the repository\n+\thas no uncommitted changes to tracked files. Otherwise it\n+\temits an error message of the form `Cannot :\n+\t. `, and dies. Example:\n++\n+----------------\n+require_clean_work_tree rebase \"Please commit or stash them.\"\n+----------------\n+\n get_author_ident_from_commit::\n \toutputs code for use with eval to set the GIT_AUTHOR_NAME,\n \tGIT_AUTHOR_EMAIL and GIT_AUTHOR_DATE variables for a given commit.\n-- \n1.7.8.484.gdad4270\n"},{"id":"181538","messageId":"7vd3bjj78h.fsf@alter.siamese.dyndns.org","threadId":"29211","inReplyTo":"23d761193dcf25f36206adc3d392e8578c566cd7.1324412815.git.trast@student.ethz.ch","subject":"Re: [PATCH v2] git-sh-setup: make require_clean_work_tree part of the interface","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-12-20T20:52:46Z","receivedAt":"2011-12-20T20:52:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Thomas Rast writes:\n\n> 92c62a3 (Porcelain scripts: Rewrite cryptic \"needs update\" error\n> message, 2010-10-19) refactored git's own checking to a function in\n> git-sh-setup. This is a very useful thing for script writers, so\n> document it.\n>\n> Signed-off-by: Thomas Rast \n> ---\n> Documentation/git-sh-setup.txt | 10 ++++++++++\n> 1 files changed, 10 insertions(+), 0 deletions(-)\n>\n> diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt\n> index a2f346c..9a0e574 100644\n> --- a/Documentation/git-sh-setup.txt\n> +++ b/Documentation/git-sh-setup.txt\n> @@ -68,6 +68,16 @@ require_work_tree_exists::\n> \tcd_to_toplevel, which is impossible to do if there is no\n> \tworking tree.\n> \n> +require_clean_work_tree []::\n> +\tchecks that the working tree associated with the repository\n> +\thas no uncommitted changes to tracked files. Otherwise it\n> +\temits an error message of the form `Cannot :\n> +\t. `, and dies. Example:\n\nDoesn't it also enforce cleanliness on the index, not just the working tree?\n\n> ++\n> +----------------\n> +require_clean_work_tree rebase \"Please commit or stash them.\"\n> +----------------\n> +\n> get_author_ident_from_commit::\n> \toutputs code for use with eval to set the GIT_AUTHOR_NAME,\n> \tGIT_AUTHOR_EMAIL and GIT_AUTHOR_DATE variables for a given commit.\n"},{"id":"181541","messageId":"b121d918166dea3b578b075ac6b794967c4bdcbe.1324415678.git.trast@student.ethz.ch","threadId":"29211","inReplyTo":"7vd3bjj78h.fsf@alter.siamese.dyndns.org","subject":"[PATCH v3] git-sh-setup: make require_clean_work_tree part of the interface","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2011-12-20T21:42:39Z","receivedAt":"2011-12-20T21:42:39Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"92c62a3 (Porcelain scripts: Rewrite cryptic \"needs update\" error\nmessage, 2010-10-19) refactored git's own checking to a function in\ngit-sh-setup. This is a very useful thing for script writers, so\ndocument it.\n\nSigned-off-by: Thomas Rast \n---\n\nJunio C Hamano writes:\n\n> Thomas Rast writes:\n> \n> > +require_clean_work_tree []::\n> > +\tchecks that the working tree associated with the repository\n> > +\thas no uncommitted changes to tracked files. Otherwise it\n> > +\temits an error message of the form `Cannot :\n> > +\t. `, and dies. Example:\n> \n> Doesn't it also enforce cleanliness on the index, not just the working tree?\n\nOf course. Here's the \"and index\" update.\n\nBTW neither gitglossary(7) nor git-cherry-pick(1) get this right.\n\n\n Documentation/git-sh-setup.txt | 10 ++++++++++\n 1 files changed, 10 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt\nindex a2f346c..eb08ba6 100644\n--- a/Documentation/git-sh-setup.txt\n+++ b/Documentation/git-sh-setup.txt\n@@ -68,6 +68,16 @@ require_work_tree_exists::\n \tcd_to_toplevel, which is impossible to do if there is no\n \tworking tree.\n \n+require_clean_work_tree []::\n+\tchecks that the working tree and index associated with the\n+\trepository have no uncommitted changes to tracked files.\n+\tOtherwise it emits an error message of the form `Cannot\n+\t: . `, and dies. Example:\n++\n+----------------\n+require_clean_work_tree rebase \"Please commit or stash them.\"\n+----------------\n+\n get_author_ident_from_commit::\n \toutputs code for use with eval to set the GIT_AUTHOR_NAME,\n \tGIT_AUTHOR_EMAIL and GIT_AUTHOR_DATE variables for a given commit.\n-- \n1.7.8.484.gdad4270\n"},{"id":"181542","messageId":"7vzkemj3ul.fsf@alter.siamese.dyndns.org","threadId":"29211","inReplyTo":"b121d918166dea3b578b075ac6b794967c4bdcbe.1324415678.git.trast@student.ethz.ch","subject":"Re: [PATCH v3] git-sh-setup: make require_clean_work_tree part of the interface","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-12-20T22:05:54Z","receivedAt":"2011-12-20T22:05:54Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Thanks, will queue.\n"}]}