From: Jonathan Nieder <jrnieder@gmail.com>
Date: Thu, 04 Nov 2010 18:02:42 GMT
Subject: Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings
Message-ID: <20101104180242.GA16431@burratino>
In-Reply-To: <20101104174917.GA30628@sigill.intra.peff.net>

Jeff King wrote:

>   # diff between index and working tree
>   git diff [options] [--] [<path>...]
> 
>   # diff between HEAD and index
>   git diff --cached [options] [--] [<path>...]
> 
>   # diff between commit and working tree
>   git diff [options] <commit> [--] [<path>...]
> 
>   # diff between commit and index
>   git diff --cached [options] <commit> [--] [<path>...]
> 
>   # diff between commits
>   git diff [options] <commit> <commit> [--] [<path>...]
> 
>   # diff two paths
>   git diff [options] [--] <path> <path>
> 
> which obviously is way more verbose

Yes, that's way more verbose than a typical manpage synopsis.
For example, from printf(3):

SYNOPSIS
       #include <stdio.h>

       int printf(const char *format, ...);
       int fprintf(FILE *stream, const char *format, ...);
       int sprintf(char *str, const char *format, ...);
       int snprintf(char *str, size_t size, const char *format, ...);

       #include <stdarg.h>

       int vprintf(const char *format, va_list ap);
       int vfprintf(FILE *stream, const char *format, va_list ap);
       int vsprintf(char *str, const char *format, va_list ap);
       int vsnprintf(char *str, size_t size, const char *format, va_list ap);

   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

       snprintf(), vsnprintf(): _BSD_SOURCE || _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE; or cc -std=c99

which would suggest that for git-diff(!) we should say something like:

SYNOPSIS

	git diff [options] [--] [<path>...]
	git diff [options] --cached [--] [<path>...]
	git diff [options] <commit> [--] [<path>...]
	git diff [options] --cached <commit> [--] [<path>...]
	git diff [options] <commit> <commit> [--] [<path>...]
	git diff [options] --no-index [--] <path> <path>

I would rather treat --cached as one of the options ("instead of
comparing the worktree, compare its cached content in the index to the
specified commit"), and if I were running the world, I'd leave off the
[options]. :)

SYNOPSIS

	git diff [--] [<path>...]
	git diff <commit> [--] [<path>...]
	git diff <commit> <commit> [--] [<path>...]
	git diff --no-index [--] <path> <path>

perhaps with some kind of reminder about --cached:

	The first two forms accept a --cached option to compare
	to staged content in the index instead of the work tree.