threads / patch / 43552

patchRe: [PATCH] Document git-runstatus

Subject: Re: [PATCH] Document git-runstatus

## tl;dr

12 messages between Nov 18, 2006 and Nov 20, 2006. Diffs are folded; open one to read it.

replies: 11people: 7as markdown or json

Rene Scharfe· Nov 18, 2006, 14:15 UTC · lore

[PATCH] Document git-runstatus

I copied most of the text from git-status.txt.
Signed-off-by: Rene Scharfe <rene.scharfe@lsrfire.ath.cx>
---
 Documentation/git-runstatus.txt |   66 +++++++++++++++++++++++++++++++++++++++
 builtin-runstatus.c             |    2 +-
 2 files changed, 67 insertions(+), 1 deletions(-)
Show changes to 2 files +67 −1

Documentation/git-runstatus.txt, builtin-runstatus.c

diff --git a/Documentation/git-runstatus.txt b/Documentation/git-runstatus.txt
new file mode 100644
index 0000000..c144c7b
--- /dev/null
+++ b/Documentation/git-runstatus.txt
@@ -0,0 +1,66 @@
+git-runstatus(1)
+================
+
+NAME
+----
+git-runstatus - Show working tree status
+
+
+SYNOPSIS
+--------
+'git-runstatus' [--color|--nocolor] [--amend] [--verbose] [--untracked]
+
+
+DESCRIPTION
+-----------
+Examines paths in the working tree that has changes unrecorded
+to the index file, and changes between the index file and the
+current HEAD commit.  The former paths are what you _could_
+commit by running 'git-update-index' before running 'git
+commit', and the latter paths are what you _would_ commit by
+running 'git commit'.
+
+If there is no path that is different between the index file and
+the current HEAD commit, the command exits with non-zero
+status.
+
+
+OPTIONS
+-------
+--color::
+	Show colored status, highlighting modified file names.
+
+--nocolor::
+	Turn off coloring.
+
+--amend::
+	Show status based on HEAD^1, not HEAD, i.e. show what
+	'git-commit --amend' would do.
+
+--verbose::
+	Show unified diff of all file changes.
+
+--untracked::
+	Show files in untracked directories, too.  Without this
+	option only its name and a trailing slash are displayed
+	for each untracked directory.
+
+
+OUTPUT
+------
+The output from this command is designed to be used as a commit
+template comments, and all the output lines are prefixed with '#'.
+
+
+Author
+------
+Written by Jeff King.
+
+Documentation
+--------------
+Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/builtin-runstatus.c b/builtin-runstatus.c
index 303c556..0b63037 100644
--- a/builtin-runstatus.c
+++ b/builtin-runstatus.c
@@ -4,7 +4,7 @@
 extern int wt_status_use_color;
 
 static const char runstatus_usage[] =
-"git-runstatus [--color|--nocolor] [--amend] [--verbose]";
+"git-runstatus [--color|--nocolor] [--amend] [--verbose] [--untracked]";
 
 int cmd_runstatus(int argc, const char **argv, const char *prefix)
 {
-- 
1.4.4
Sean· Nov 18, 2006, 14:26 UTC · re: Rene Scharfe · lore

On Sat, 18 Nov 2006 15:15:49 +0100 Rene Scharfe <rene.scharfe@lsrfire.ath.cx> wrote:

> I copied most of the text from git-status.txt.
[...]	
> +git-runstatus - Show working tree status

How is git-runstatus different from "git status"? Should this command be viewed simply as plumbing, and if so does it deserve a man page or just textual documentation in the source?

Petr Baudis· Nov 18, 2006, 14:35 UTC · lore
On Sat, Nov 18, 2006 at 03:26:44PM CET, Sean wrote:
Show 6 quoted lines
> On Sat, 18 Nov 2006 15:15:49 +0100
> Rene Scharfe <rene.scharfe@lsrfire.ath.cx> wrote:
> 
> > I copied most of the text from git-status.txt.
> [...]	
> > +git-runstatus - Show working tree status
Don't forget to add it to the list of commands.
> How is git-runstatus different from "git status"?
I have the same question.
> Should this command be viewed simply as plumbing, and if so does it
> deserve a man page or just textual documentation in the source?
All commands deserve a man page.
-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
The meaning of Stonehenge in Traflamadorian, when viewed from above, is:
"Replacement part being rushed with all possible speed."
Rene Scharfe· Nov 18, 2006, 15:04 UTC · re: Petr Baudis · lore
Petr Baudis schrieb:
Show 9 quoted lines
> On Sat, Nov 18, 2006 at 03:26:44PM CET, Sean wrote:
>> On Sat, 18 Nov 2006 15:15:49 +0100
>> Rene Scharfe <rene.scharfe@lsrfire.ath.cx> wrote:
>>
>>> I copied most of the text from git-status.txt.
>> [...]	
>>> +git-runstatus - Show working tree status
> 
> Don't forget to add it to the list of commands.
Good catch, thanks.  An incremental patch follows below.
>> How is git-runstatus different from "git status"?
> 
> I have the same question.

git-status is a wrapper around git-runstatus that takes the same options as git-commit. It could have been named 'git-commit --dry-run'.

>> Should this command be viewed simply as plumbing, and if so does it
>> deserve a man page or just textual documentation in the source?
> 
> All commands deserve a man page.
Exactly.  Even plumbers read manuals ;-).  Well, me at least.
René
Show changes to Documentation/git.txt +3 −0
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 52bc05a..63b1746 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -424,6 +424,9 @@ gitlink:git-pack-redundant[1]::
 gitlink:git-rev-list[1]::
 	Lists commit objects in reverse chronological order.
 
+gitlink:git-runstatus[1]::
+	Show working tree status.
+
 gitlink:git-show-index[1]::
 	Displays contents of a pack idx file.
Sean· Nov 18, 2006, 16:04 UTC · re: Rene Scharfe · lore

On Sat, 18 Nov 2006 16:04:43 +0100 Rene Scharfe <rene.scharfe@lsrfire.ath.cx> wrote:

> git-status is a wrapper around git-runstatus that takes the same
> options as git-commit.  It could have been named 'git-commit --dry-run'.

What could be said in the docs as to when the use of one is preferred over the other?

> > All commands deserve a man page.
> 
> Exactly.  Even plumbers read manuals ;-).  Well, me at least.

Heh, I suppose you and Petr are right. It's just that in recent discussions the great number of commands provided by Git is seen as a UI problem. Thus having two commands that seem to do the exact same thing gives more such pain for no gain.

It's possible that plumbers should not be seen as "users" but rather as coders capable of reading traditional text based (non man-page) documentation for their purposes, and man pages should only exist (or at least installed) for user level commands.

A Large Angry SCM· Nov 18, 2006, 18:20 UTC · re: Sean · lore
Sean wrote:
Show 21 quoted lines
> On Sat, 18 Nov 2006 16:04:43 +0100
> Rene Scharfe <rene.scharfe@lsrfire.ath.cx> wrote:
> 
>> git-status is a wrapper around git-runstatus that takes the same
>> options as git-commit.  It could have been named 'git-commit --dry-run'.
> 
> What could be said in the docs as to when the use of one is preferred
> over the other?
> 
>>> All commands deserve a man page.
>> Exactly.  Even plumbers read manuals ;-).  Well, me at least.
> 
> Heh, I suppose you and Petr are right.  It's just that in recent
> discussions the great number of commands provided by Git is seen
> as a UI problem.  Thus having two commands that seem to do the
> exact same thing gives more such pain for no gain.
> 
> It's possible that plumbers should not be seen as "users" but
> rather as coders capable of reading traditional text based
> (non man-page) documentation for their purposes, and man pages
> should only exist (or at least installed) for user level commands.
Sean· Nov 18, 2006, 18:49 UTC · re: A Large Angry SCM · lore

On Sat, 18 Nov 2006 10:20:54 -0800 A Large Angry SCM <gitzilla@gmail.com> wrote:

> Are you suggesting that all non section 1 man pages should not exist?
> 

No... I was wrong to suggest there shouldn't be a man page.. I guess my real concern was why this particular command was needed at all.

Really, it's not the man pages that are the problem but rather the large number of commands that are installed into the standard path that should only ever be accessed as plumbing.

The plumbing-only commands should really be installed somewhere else, and man pages for them need only be installed in a -devel package, not in the standard install.

Junio C Hamano· Nov 18, 2006, 18:49 UTC · re: Sean · lore
Sean <seanlkml@sympatico.ca> writes:
Show 8 quoted lines
> On Sat, 18 Nov 2006 16:04:43 +0100
> Rene Scharfe <rene.scharfe@lsrfire.ath.cx> wrote:
>
>> git-status is a wrapper around git-runstatus that takes the same
>> options as git-commit.  It could have been named 'git-commit --dry-run'.
>
> What could be said in the docs as to when the use of one is preferred
> over the other?

You should treat git-runstatus the same way as you would treat "git-merge-recursive". It strictly is a helper and you never use it by itself.

It takes the parts that are too cumbersome to be enhanced in shell script from the old git-status script, and rewrites it in C.

"git-status $args" is to give a preview of the commit that would be made with "git-commit $args" (where $args can be things like -a, $paths...). The part that still remain as script in git-commit and git-status performs the gory details of index preparation for the next commit, and tells git-runstatus to show the status of that index and the working tree relative to the current HEAD.

Most notably, running "git-update-index --refresh" part is still
done in the script part that calls runstatus, so in a
cache-dirty but otherwise clean tree, running git-runstatus and
then git-status (without any parameters) in this order would
show cache dirty paths in the former but not in the latter (nor
after the latter runs once, since it calls --refresh).
 
Sean· Nov 18, 2006, 20:04 UTC · lore

On Sat, 18 Nov 2006 11:37:14 -0800 A Large Angry SCM <gitzilla@gmail.com> wrote:

> I disagree. If a command is install on a system, it's man 
> pages/documentation should also be installed.

Well this isn't a huge issue. One point you made though that struck a chord is that many of the commands should probably not be in section 1.

> I'm also not convinced that there are a "large number of commands [...] 
> that should only ever be accessed as plumbing". I am convinced, however, 
> that there are a number of relatively low level commands with poor user 
> interfaces that are useful on their own.

Is there really a reason for a git user to access these from the command line rather than a script:

commit-tree, diff-files, diff-index, diff-tree, for-each-ref, hash-object, http-fetch, http-push, index-pack, local-fetch, merge-base, merge-index, merge-octopus, merge-one-file, merge-ours, merge-recur, merge-recursive, merge-recursive-old, merge-resolve, merge-stupid, merge-tree, receive-pack, runstatus, ssh-fetch, ssh-pull, ssh-push, ssh-upload, symbolic-ref, unpack-file, unpack-objects, update-ref, upload-archive, upload-pack, upload-tar, write-tree

Not a complete list, and maybe i overlooked something in there that is needed from the command line, but for the most part these could be installed somewhere other than the users path.

Petr Baudis· Nov 19, 2006, 18:13 UTC · lore
On Sat, Nov 18, 2006 at 09:04:31PM CET, Sean wrote:
Show 9 quoted lines
> On Sat, 18 Nov 2006 11:37:14 -0800
> A Large Angry SCM <gitzilla@gmail.com> wrote:
> 
> > I disagree. If a command is install on a system, it's man 
> > pages/documentation should also be installed.
> 
> Well this isn't a huge issue.  One point you made though that struck
> a chord is that many of the commands should probably not be in
> section 1.

The trouble is that there's no other good place where to put them. But perhaps we can get away with putting them to section 3? After all, Perl installs documentation for its modules to section 3 as well.

Show 19 quoted lines
> > I'm also not convinced that there are a "large number of commands [...] 
> > that should only ever be accessed as plumbing". I am convinced, however, 
> > that there are a number of relatively low level commands with poor user 
> > interfaces that are useful on their own.
> 
> Is there really a reason for a git user to access these from the
> command line rather than a script:
> 
> commit-tree, diff-files, diff-index, diff-tree, for-each-ref,
> hash-object, http-fetch, http-push, index-pack, local-fetch,
> merge-base, merge-index, merge-octopus, merge-one-file, merge-ours,
> merge-recur, merge-recursive, merge-recursive-old, merge-resolve,
> merge-stupid, merge-tree, receive-pack, runstatus, ssh-fetch, ssh-pull,
> ssh-push, ssh-upload, symbolic-ref, unpack-file, unpack-objects,
> update-ref, upload-archive, upload-pack, upload-tar, write-tree
> 
> Not a complete list, and maybe i overlooked something in there
> that is needed from the command line, but for the most part 
> these could be installed somewhere other than the users path.

There certainly are reasons, but the situations where it is needed is sufficiently rare; I think that's a reason good enough, when doing something exotic like recovery of a corrupted repository it's ok to have to do something slightly special to execute a lowlevel command.

It has been proposed for a long time that we put the "pure plumbing" commands to /usr/libexec/git/ or somewhere there (some say /usr/libexec/ is obsolete), and I think it would be a great move. Note that nowadays the transition needs to be done carefully because of backwards compatibility.

BTW, I've finally found a fine example of situation parallel to Git: TeX! There are the core TeX commands (plumbing) and plain TeX (basic porcelain) on top of that as well as a bunch of other macro sets (other porcelains). Now I need to dig out The TeXbook from wherever I've put it to see how did Knuth deal with it, documentation-wise.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
The meaning of Stonehenge in Traflamadorian, when viewed from above, is:
"Replacement part being rushed with all possible speed."
Joshua N Pritikin· Nov 20, 2006, 07:15 UTC · re: Petr Baudis · lore
On Sun, Nov 19, 2006 at 07:13:08PM +0100, Petr Baudis wrote:
Show 5 quoted lines
> BTW, I've finally found a fine example of situation parallel to Git:
> TeX!  There are the core TeX commands (plumbing) and plain TeX (basic
> porcelain) on top of that as well as a bunch of other macro sets (other
> porcelains). Now I need to dig out The TeXbook from wherever I've put it
> to see how did Knuth deal with it, documentation-wise.

Gahh! Please don't use TeX as an example. As far as I know, TeX doesn't offer lexical scope. Hence, action-at-a-distance is commonplace which makes program execution extremely difficult for mere mortals to predict. I am constantly amazed at popularity of TeX, in spite of its grave deficiencies. Perhaps there isn't a good alternative yet.

Jakub Narebski· Nov 20, 2006, 08:11 UTC · re: Joshua N Pritikin · lore
Joshua N Pritikin wrote:
Show 9 quoted lines
> On Sun, Nov 19, 2006 at 07:13:08PM +0100, Petr Baudis wrote:
>> BTW, I've finally found a fine example of situation parallel to Git:
>> TeX!  There are the core TeX commands (plumbing) and plain TeX (basic
>> porcelain) on top of that as well as a bunch of other macro sets (other
>> porcelains). Now I need to dig out The TeXbook from wherever I've put it
>> to see how did Knuth deal with it, documentation-wise.
> 
> Gahh! Please don't use TeX as an example. As far as I know, TeX doesn't 
> offer lexical scope. 
It offers grouping.
> Hence, action-at-a-distance is commonplace which  
> makes program execution extremely difficult for mere mortals to 
> predict. I am constantly amazed at popularity of TeX, in spite of its 
> grave deficiencies. Perhaps there isn't a good alternative yet.

TeX (even plain TeX) is like assembler of programming languages. One does usually use one of the TeX macros sets, like LaTeX, ConTeXt or texinfo.

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

← back to recent threads