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.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html