{"thread":{"id":"43552","subject":"Re: [PATCH] Document git-runstatus","startedAt":"2006-11-18T14:15:49Z","lastAt":"2006-11-20T08:11:48Z","messageCount":12,"participants":["A Large Angry SCM","Petr Baudis","Jakub Narebski","Junio C Hamano","Rene Scharfe","Sean","Joshua N Pritikin"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"297580","messageId":"455F1595.9020009@lsrfire.ath.cx","threadId":"43552","inReplyTo":null,"subject":"[PATCH] Document git-runstatus","fromName":"Rene Scharfe","fromEmail":"rene.scharfe@lsrfire.ath.cx","sentAt":"2006-11-18T14:15:49Z","receivedAt":"2006-11-18T14:15:49Z","isPatch":true,"sender":{"key":"l.s.r@web.de","avatar":"https://avatars.githubusercontent.com/u/26122331?v=4"},"body":"I copied most of the text from git-status.txt.\n\nSigned-off-by: Rene Scharfe \n---\n Documentation/git-runstatus.txt | 66 +++++++++++++++++++++++++++++++++++++++\n builtin-runstatus.c | 2 +-\n 2 files changed, 67 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git-runstatus.txt b/Documentation/git-runstatus.txt\nnew file mode 100644\nindex 0000000..c144c7b\n--- /dev/null\n+++ b/Documentation/git-runstatus.txt\n@@ -0,0 +1,66 @@\n+git-runstatus(1)\n+================\n+\n+NAME\n+----\n+git-runstatus - Show working tree status\n+\n+\n+SYNOPSIS\n+--------\n+'git-runstatus' [--color|--nocolor] [--amend] [--verbose] [--untracked]\n+\n+\n+DESCRIPTION\n+-----------\n+Examines paths in the working tree that has changes unrecorded\n+to the index file, and changes between the index file and the\n+current HEAD commit. The former paths are what you _could_\n+commit by running 'git-update-index' before running 'git\n+commit', and the latter paths are what you _would_ commit by\n+running 'git commit'.\n+\n+If there is no path that is different between the index file and\n+the current HEAD commit, the command exits with non-zero\n+status.\n+\n+\n+OPTIONS\n+-------\n+--color::\n+\tShow colored status, highlighting modified file names.\n+\n+--nocolor::\n+\tTurn off coloring.\n+\n+--amend::\n+\tShow status based on HEAD^1, not HEAD, i.e. show what\n+\t'git-commit --amend' would do.\n+\n+--verbose::\n+\tShow unified diff of all file changes.\n+\n+--untracked::\n+\tShow files in untracked directories, too. Without this\n+\toption only its name and a trailing slash are displayed\n+\tfor each untracked directory.\n+\n+\n+OUTPUT\n+------\n+The output from this command is designed to be used as a commit\n+template comments, and all the output lines are prefixed with '#'.\n+\n+\n+Author\n+------\n+Written by Jeff King.\n+\n+Documentation\n+--------------\n+Documentation by David Greaves, Junio C Hamano and the git-list .\n+\n+GIT\n+---\n+Part of the gitlink:git[7] suite\n+\ndiff --git a/builtin-runstatus.c b/builtin-runstatus.c\nindex 303c556..0b63037 100644\n--- a/builtin-runstatus.c\n+++ b/builtin-runstatus.c\n@@ -4,7 +4,7 @@\n extern int wt_status_use_color;\n \n static const char runstatus_usage[] =\n-\"git-runstatus [--color|--nocolor] [--amend] [--verbose]\";\n+\"git-runstatus [--color|--nocolor] [--amend] [--verbose] [--untracked]\";\n \n int cmd_runstatus(int argc, const char **argv, const char *prefix)\n {\n-- \n1.4.4\n"},{"id":"296287","messageId":"BAYC1-PASMTP03FF5D34586546629C92BBAEEF0@CEZ.ICE","threadId":"43552","inReplyTo":"455F1595.9020009@lsrfire.ath.cx","subject":"Re: [PATCH] Document git-runstatus","fromName":"Sean","fromEmail":"seanlkml@sympatico.ca","sentAt":"2006-11-18T14:26:44Z","receivedAt":"2006-11-18T14:26:44Z","isPatch":true,"sender":{"key":"seanlkml@sympatico.ca","avatar":"https://gravatar.com/avatar/f92923f54fc08c401fc59b71829d4b89e9b8087fbba45ff87c82e6a83aee02ae?d=mp&s=160"},"body":"On Sat, 18 Nov 2006 15:15:49 +0100\nRene Scharfe wrote:\n\n> I copied most of the text from git-status.txt.\n[...]\t\n> +git-runstatus - Show working tree status\n\nHow is git-runstatus different from \"git status\"? Should this command be\nviewed simply as plumbing, and if so does it deserve a man page or just\ntextual documentation in the source?\n\n"},{"id":"296101","messageId":"20061118143511.GM7201@pasky.or.cz","threadId":"43552","inReplyTo":"20061118092644.a9f15669.seanlkml@sympatico.ca","subject":"Re: [PATCH] Document git-runstatus","fromName":"Petr Baudis","fromEmail":"pasky@suse.cz","sentAt":"2006-11-18T14:35:11Z","receivedAt":"2006-11-18T14:35:11Z","isPatch":true,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"On Sat, Nov 18, 2006 at 03:26:44PM CET, Sean wrote:\n> On Sat, 18 Nov 2006 15:15:49 +0100\n> Rene Scharfe wrote:\n> \n> > I copied most of the text from git-status.txt.\n> [...]\t\n> > +git-runstatus - Show working tree status\n\nDon't forget to add it to the list of commands.\n\n> How is git-runstatus different from \"git status\"?\n\nI have the same question.\n\n> Should this command be viewed simply as plumbing, and if so does it\n> deserve a man page or just textual documentation in the source?\n\nAll commands deserve a man page.\n\n-- \n\t\t\t\tPetr \"Pasky\" Baudis\nStuff: http://pasky.or.cz/\nThe meaning of Stonehenge in Traflamadorian, when viewed from above, is:\n\"Replacement part being rushed with all possible speed.\"\n"},{"id":"296276","messageId":"455F210B.8000107@lsrfire.ath.cx","threadId":"43552","inReplyTo":"20061118143511.GM7201@pasky.or.cz","subject":"Re: [PATCH] Document git-runstatus","fromName":"Rene Scharfe","fromEmail":"rene.scharfe@lsrfire.ath.cx","sentAt":"2006-11-18T15:04:43Z","receivedAt":"2006-11-18T15:04:43Z","isPatch":true,"sender":{"key":"l.s.r@web.de","avatar":"https://avatars.githubusercontent.com/u/26122331?v=4"},"body":"Petr Baudis schrieb:\n> On Sat, Nov 18, 2006 at 03:26:44PM CET, Sean wrote:\n>> On Sat, 18 Nov 2006 15:15:49 +0100\n>> Rene Scharfe wrote:\n>>\n>>> I copied most of the text from git-status.txt.\n>> [...]\t\n>>> +git-runstatus - Show working tree status\n> \n> Don't forget to add it to the list of commands.\n\nGood catch, thanks. An incremental patch follows below.\n\n>> How is git-runstatus different from \"git status\"?\n> \n> I have the same question.\n\ngit-status is a wrapper around git-runstatus that takes the same\noptions as git-commit. It could have been named 'git-commit --dry-run'.\n\n>> Should this command be viewed simply as plumbing, and if so does it\n>> deserve a man page or just textual documentation in the source?\n> \n> All commands deserve a man page.\n\nExactly. Even plumbers read manuals ;-). Well, me at least.\n\nRené\n\n\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 52bc05a..63b1746 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -424,6 +424,9 @@ gitlink:git-pack-redundant[1]::\n gitlink:git-rev-list[1]::\n \tLists commit objects in reverse chronological order.\n \n+gitlink:git-runstatus[1]::\n+\tShow working tree status.\n+\n gitlink:git-show-index[1]::\n \tDisplays contents of a pack idx file.\n"},{"id":"298587","messageId":"BAYC1-PASMTP06C814AB518D7544770C01AEEF0@CEZ.ICE","threadId":"43552","inReplyTo":"455F210B.8000107@lsrfire.ath.cx","subject":"Re: [PATCH] Document git-runstatus","fromName":"Sean","fromEmail":"seanlkml@sympatico.ca","sentAt":"2006-11-18T16:04:20Z","receivedAt":"2006-11-18T16:04:20Z","isPatch":true,"sender":{"key":"seanlkml@sympatico.ca","avatar":"https://gravatar.com/avatar/f92923f54fc08c401fc59b71829d4b89e9b8087fbba45ff87c82e6a83aee02ae?d=mp&s=160"},"body":"On Sat, 18 Nov 2006 16:04:43 +0100\nRene Scharfe wrote:\n\n> git-status is a wrapper around git-runstatus that takes the same\n> options as git-commit. It could have been named 'git-commit --dry-run'.\n\nWhat could be said in the docs as to when the use of one is preferred\nover the other?\n\n> > All commands deserve a man page.\n> \n> Exactly. Even plumbers read manuals ;-). Well, me at least.\n\nHeh, I suppose you and Petr are right. It's just that in recent\ndiscussions the great number of commands provided by Git is seen\nas a UI problem. Thus having two commands that seem to do the\nexact same thing gives more such pain for no gain.\n\nIt's possible that plumbers should not be seen as \"users\" but\nrather as coders capable of reading traditional text based\n(non man-page) documentation for their purposes, and man pages\nshould only exist (or at least installed) for user level commands.\n\n"},{"id":"295431","messageId":"455F4F06.3090902@gmail.com","threadId":"43552","inReplyTo":"BAYC1-PASMTP06C814AB518D7544770C01AEEF0@CEZ.ICE","subject":"Re: [PATCH] Document git-runstatus","fromName":"A Large Angry SCM","fromEmail":"gitzilla@gmail.com","sentAt":"2006-11-18T18:20:54Z","receivedAt":"2006-11-18T18:20:54Z","isPatch":true,"sender":{"key":"gitzilla@gmail.com","avatar":"https://gravatar.com/avatar/354625c442439908ff3dd99757dee330e29e9df7847472384faf7a00add247fb?d=mp&s=160"},"body":"Sean wrote:\n> On Sat, 18 Nov 2006 16:04:43 +0100\n> Rene Scharfe wrote:\n> \n>> git-status is a wrapper around git-runstatus that takes the same\n>> options as git-commit. It could have been named 'git-commit --dry-run'.\n> \n> What could be said in the docs as to when the use of one is preferred\n> over the other?\n> \n>>> All commands deserve a man page.\n>> Exactly. Even plumbers read manuals ;-). Well, me at least.\n> \n> Heh, I suppose you and Petr are right. It's just that in recent\n> discussions the great number of commands provided by Git is seen\n> as a UI problem. Thus having two commands that seem to do the\n> exact same thing gives more such pain for no gain.\n> \n> It's possible that plumbers should not be seen as \"users\" but\n> rather as coders capable of reading traditional text based\n> (non man-page) documentation for their purposes, and man pages\n> should only exist (or at least installed) for user level commands.\n\n"},{"id":"296028","messageId":"7vfycgegk6.fsf@assigned-by-dhcp.cox.net","threadId":"43552","inReplyTo":"BAYC1-PASMTP06C814AB518D7544770C01AEEF0@CEZ.ICE","subject":"Re: [PATCH] Document git-runstatus","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2006-11-18T18:49:13Z","receivedAt":"2006-11-18T18:49:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sean writes:\n\n> On Sat, 18 Nov 2006 16:04:43 +0100\n> Rene Scharfe wrote:\n>\n>> git-status is a wrapper around git-runstatus that takes the same\n>> options as git-commit. It could have been named 'git-commit --dry-run'.\n>\n> What could be said in the docs as to when the use of one is preferred\n> over the other?\n\nYou should treat git-runstatus the same way as you would treat\n\"git-merge-recursive\". It strictly is a helper and you never\nuse it by itself.\n\nIt takes the parts that are too cumbersome to be enhanced in\nshell script from the old git-status script, and rewrites it in\nC.\n\n\"git-status $args\" is to give a preview of the commit that would\nbe made with \"git-commit $args\" (where $args can be things like\n-a, $paths...). The part that still remain as script in\ngit-commit and git-status performs the gory details of index\npreparation for the next commit, and tells git-runstatus to show\nthe status of that index and the working tree relative to the\ncurrent HEAD.\n\nMost notably, running \"git-update-index --refresh\" part is still\ndone in the script part that calls runstatus, so in a\ncache-dirty but otherwise clean tree, running git-runstatus and\nthen git-status (without any parameters) in this order would\nshow cache dirty paths in the former but not in the latter (nor\nafter the latter runs once, since it calls --refresh).\n \n\n"},{"id":"297947","messageId":"BAYC1-PASMTP06DE3E6CFF9E49C2BF16C7AEEF0@CEZ.ICE","threadId":"43552","inReplyTo":"455F4F06.3090902@gmail.com","subject":"Re: [PATCH] Document git-runstatus","fromName":"Sean","fromEmail":"seanlkml@sympatico.ca","sentAt":"2006-11-18T18:49:25Z","receivedAt":"2006-11-18T18:49:25Z","isPatch":true,"sender":{"key":"seanlkml@sympatico.ca","avatar":"https://gravatar.com/avatar/f92923f54fc08c401fc59b71829d4b89e9b8087fbba45ff87c82e6a83aee02ae?d=mp&s=160"},"body":"On Sat, 18 Nov 2006 10:20:54 -0800\nA Large Angry SCM wrote:\n\n\n> Are you suggesting that all non section 1 man pages should not exist?\n> \n\nNo... I was wrong to suggest there shouldn't be a man page.. I\nguess my real concern was why this particular command was needed\nat all.\n\nReally, it's not the man pages that are the problem but rather\nthe large number of commands that are installed into the standard\npath that should only ever be accessed as plumbing.\n\nThe plumbing-only commands should really be installed somewhere\nelse, and man pages for them need only be installed in a\n-devel package, not in the standard install.\n\n"},{"id":"298758","messageId":"BAYC1-PASMTP103AEE0623ACD61079E916AEEF0@CEZ.ICE","threadId":"43552","inReplyTo":"455F60EA.2080009@gmail.com","subject":"Re: [PATCH] Document git-runstatus","fromName":"Sean","fromEmail":"seanlkml@sympatico.ca","sentAt":"2006-11-18T20:04:31Z","receivedAt":"2006-11-18T20:04:31Z","isPatch":true,"sender":{"key":"seanlkml@sympatico.ca","avatar":"https://gravatar.com/avatar/f92923f54fc08c401fc59b71829d4b89e9b8087fbba45ff87c82e6a83aee02ae?d=mp&s=160"},"body":"On Sat, 18 Nov 2006 11:37:14 -0800\nA Large Angry SCM wrote:\n\n> I disagree. If a command is install on a system, it's man \n> pages/documentation should also be installed.\n\nWell this isn't a huge issue. One point you made though that struck\na chord is that many of the commands should probably not be in\nsection 1.\n\n> I'm also not convinced that there are a \"large number of commands [...] \n> that should only ever be accessed as plumbing\". I am convinced, however, \n> that there are a number of relatively low level commands with poor user \n> interfaces that are useful on their own.\n\nIs there really a reason for a git user to access these from the\ncommand line rather than a script:\n\ncommit-tree, diff-files, diff-index, diff-tree, for-each-ref,\nhash-object, http-fetch, http-push, index-pack, local-fetch,\nmerge-base, merge-index, merge-octopus, merge-one-file, merge-ours,\nmerge-recur, merge-recursive, merge-recursive-old, merge-resolve,\nmerge-stupid, merge-tree, receive-pack, runstatus, ssh-fetch, ssh-pull,\nssh-push, ssh-upload, symbolic-ref, unpack-file, unpack-objects,\nupdate-ref, upload-archive, upload-pack, upload-tar, write-tree\n\nNot a complete list, and maybe i overlooked something in there\nthat is needed from the command line, but for the most part \nthese could be installed somewhere other than the users path.\n\n"},{"id":"295464","messageId":"20061119181307.GY7201@pasky.or.cz","threadId":"43552","inReplyTo":"20061118150431.81076072.seanlkml@sympatico.ca","subject":"Re: [PATCH] Document git-runstatus","fromName":"Petr Baudis","fromEmail":"pasky@suse.cz","sentAt":"2006-11-19T18:13:08Z","receivedAt":"2006-11-19T18:13:08Z","isPatch":true,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"On Sat, Nov 18, 2006 at 09:04:31PM CET, Sean wrote:\n> On Sat, 18 Nov 2006 11:37:14 -0800\n> A Large Angry SCM wrote:\n> \n> > I disagree. If a command is install on a system, it's man \n> > pages/documentation should also be installed.\n> \n> Well this isn't a huge issue. One point you made though that struck\n> a chord is that many of the commands should probably not be in\n> section 1.\n\nThe trouble is that there's no other good place where to put them. But\nperhaps we can get away with putting them to section 3? After all, Perl\ninstalls documentation for its modules to section 3 as well.\n\n> > I'm also not convinced that there are a \"large number of commands [...] \n> > that should only ever be accessed as plumbing\". I am convinced, however, \n> > that there are a number of relatively low level commands with poor user \n> > interfaces that are useful on their own.\n> \n> Is there really a reason for a git user to access these from the\n> command line rather than a script:\n> \n> commit-tree, diff-files, diff-index, diff-tree, for-each-ref,\n> hash-object, http-fetch, http-push, index-pack, local-fetch,\n> merge-base, merge-index, merge-octopus, merge-one-file, merge-ours,\n> merge-recur, merge-recursive, merge-recursive-old, merge-resolve,\n> merge-stupid, merge-tree, receive-pack, runstatus, ssh-fetch, ssh-pull,\n> ssh-push, ssh-upload, symbolic-ref, unpack-file, unpack-objects,\n> update-ref, upload-archive, upload-pack, upload-tar, write-tree\n> \n> Not a complete list, and maybe i overlooked something in there\n> that is needed from the command line, but for the most part \n> these could be installed somewhere other than the users path.\n\nThere certainly are reasons, but the situations where it is needed is\nsufficiently rare; I think that's a reason good enough, when doing\nsomething exotic like recovery of a corrupted repository it's ok to have\nto do something slightly special to execute a lowlevel command.\n\nIt has been proposed for a long time that we put the \"pure plumbing\"\ncommands to /usr/libexec/git/ or somewhere there (some say /usr/libexec/\nis obsolete), and I think it would be a great move. Note that nowadays\nthe transition needs to be done carefully because of backwards\ncompatibility.\n\n\nBTW, I've finally found a fine example of situation parallel to Git:\nTeX! There are the core TeX commands (plumbing) and plain TeX (basic\nporcelain) on top of that as well as a bunch of other macro sets (other\nporcelains). Now I need to dig out The TeXbook from wherever I've put it\nto see how did Knuth deal with it, documentation-wise.\n\n-- \n\t\t\t\tPetr \"Pasky\" Baudis\nStuff: http://pasky.or.cz/\nThe meaning of Stonehenge in Traflamadorian, when viewed from above, is:\n\"Replacement part being rushed with all possible speed.\"\n"},{"id":"298919","messageId":"20061120071529.GF3315@always.joy.eth.net","threadId":"43552","inReplyTo":"20061119181307.GY7201@pasky.or.cz","subject":"Re: [PATCH] Document git-runstatus","fromName":"Joshua N Pritikin","fromEmail":"jpritikin@pobox.com","sentAt":"2006-11-20T07:15:29Z","receivedAt":"2006-11-20T07:15:29Z","isPatch":true,"sender":{"key":"jpritikin@pobox.com","avatar":"https://gravatar.com/avatar/3f2561fdd7efac4e127dc65ac7e06f044069c115dcc94d0ac540f4126d47759d?d=mp&s=160"},"body":"On Sun, Nov 19, 2006 at 07:13:08PM +0100, Petr Baudis wrote:\n> BTW, I've finally found a fine example of situation parallel to Git:\n> TeX! There are the core TeX commands (plumbing) and plain TeX (basic\n> porcelain) on top of that as well as a bunch of other macro sets (other\n> porcelains). Now I need to dig out The TeXbook from wherever I've put it\n> to see how did Knuth deal with it, documentation-wise.\n\nGahh! Please don't use TeX as an example. As far as I know, TeX doesn't \noffer lexical scope. Hence, action-at-a-distance is commonplace which \nmakes program execution extremely difficult for mere mortals to \npredict. I am constantly amazed at popularity of TeX, in spite of its \ngrave deficiencies. Perhaps there isn't a good alternative yet.\n\n"},{"id":"295743","messageId":"ejrntd$kj$1@sea.gmane.org","threadId":"43552","inReplyTo":"20061120071529.GF3315@always.joy.eth.net","subject":"Re: [PATCH] Document git-runstatus","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2006-11-20T08:11:48Z","receivedAt":"2006-11-20T08:11:48Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Joshua N Pritikin wrote:\n\n> On Sun, Nov 19, 2006 at 07:13:08PM +0100, Petr Baudis wrote:\n>> BTW, I've finally found a fine example of situation parallel to Git:\n>> TeX! There are the core TeX commands (plumbing) and plain TeX (basic\n>> porcelain) on top of that as well as a bunch of other macro sets (other\n>> porcelains). Now I need to dig out The TeXbook from wherever I've put it\n>> to see how did Knuth deal with it, documentation-wise.\n> \n> Gahh! Please don't use TeX as an example. As far as I know, TeX doesn't \n> offer lexical scope. \n\nIt offers grouping.\n\n> Hence, action-at-a-distance is commonplace which \n> makes program execution extremely difficult for mere mortals to \n> predict. I am constantly amazed at popularity of TeX, in spite of its \n> grave deficiencies. Perhaps there isn't a good alternative yet.\n\nTeX (even plain TeX) is like assembler of programming languages. One does\nusually use one of the TeX macros sets, like LaTeX, ConTeXt or texinfo.\n-- \nJakub Narebski\nWarsaw, Poland\nShadeHawk on #git\n\n"}]}