[PATCH] Document git-runstatus

[PATCH] Document git-runstatus

[Rene Scharfe]

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

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

Re: [PATCH] Document git-runstatus

[Sean]

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?

Re: [PATCH] Document git-runstatus

[Petr Baudis]

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.

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

Re: [PATCH] Document git-runstatus

[Rene Scharfe]

Petr Baudis schrieb:
> 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é


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.

Re: [PATCH] Document git-runstatus

[Sean]

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.

Re: [PATCH] Document git-runstatus

[A Large Angry SCM]

Sean wrote:
> 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.

Re: [PATCH] Document git-runstatus

[Junio C Hamano]

Sean <seanlkml@sympatico.ca> writes:

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

Re: [PATCH] Document git-runstatus

[Sean]

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.

Re: [PATCH] Document git-runstatus

[Sean]

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.

Re: [PATCH] Document git-runstatus

[Petr Baudis]

On Sat, Nov 18, 2006 at 09:04:31PM CET, Sean wrote:
> 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.

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

Re: [PATCH] Document git-runstatus

[Joshua N Pritikin]

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

Re: [PATCH] Document git-runstatus

[Jakub Narebski]

Joshua N Pritikin wrote:

> 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