[PATCH/RFC 00/12] docs: use metavariables consistently
- From
Mark Lodato <lodatom@gmail.com>
- Date
- Mar 13, 2010, 04:52 UTC
- Message-ID
- <1268455984-19061-1-git-send-email-lodatom@gmail.com>
Based on master, 90a2bf9ca155c8e0e43d9e30197d9562dd02ea96.
This patch series is an attempt to make the documentation and usage statements consistent in how metavariables [1], such as <commit>, are used. The biggest changes are to get rid of the terms <commit-ish> and <tree-ish>, and instead prefer simple <commit> and <tree>. It ends up that almost all commands, with the exception of git-commit-tree, accept the -ish versions of these objects. The first patch --- which should be the only non-trivial change to actual code --- modifies commit-tree to accept any tree-ish. The rest of the patches should all be confined to documentation, usage statements, or code comments.
I submit this as an "RFC" because I don't expect this to be accepted right away. The change set is fairly large, and I imagine some of these changes will meet resistance. My overall goal is to make the documentation consistent and readable throughout, and I hope that this series makes progress toward that end.
[1] I say "metavariable", from Python's optparse, for lack of a better term.
Mark Lodato (12):
commit-tree: allow indirect tree references
grep docs: grep accepts a <tree-ish>, not a <tree>
fsck docs: remove outdated and useless diagnostic
docs: use <sha1> to mean unabbreviated ID
docs: differentiate between <tag> and <tagname>
docs: clarify <object>, <commit>, <tree-ish>, etc
docs: use <tree> instead of <tree-ish>
http-fetch docs: use <commit-id> consistently
docs: use <commit> instead of <commit-ish>
diff: use brackets for optional args in usage
docs: use ... instead of * for multiplicity
diff docs: remove <rev>{0,2} notationDocumentation/RelNotes-1.6.2.4.txt | 2 +- Documentation/diff-format.txt | 8 ++-- Documentation/diff-generate-patch.txt | 2 +- Documentation/git-archive.txt | 4 +- Documentation/git-checkout-index.txt | 2 +- Documentation/git-checkout.txt | 14 ++++---- Documentation/git-commit-tree.txt | 2 +- Documentation/git-describe.txt | 14 ++++---- Documentation/git-diff-index.txt | 4 +- Documentation/git-diff-tree.txt | 18 +++++----- Documentation/git-diff.txt | 4 +- Documentation/git-difftool.txt | 2 +- Documentation/git-fast-import.txt | 22 ++++++------ Documentation/git-for-each-ref.txt | 2 +- Documentation/git-fsck.txt | 5 +-- Documentation/git-http-fetch.txt | 4 +- Documentation/git-ls-files.txt | 8 ++-- Documentation/git-ls-tree.txt | 4 +- Documentation/git-merge-index.txt | 2 +- Documentation/git-mergetool.txt | 2 +- Documentation/git-name-rev.txt | 2 +- Documentation/git-pack-objects.txt | 2 +- Documentation/git-push.txt | 2 +- Documentation/git-read-tree.txt | 4 +- Documentation/git-rebase.txt | 2 +- Documentation/git-relink.txt | 2 +- Documentation/git-shortlog.txt | 2 +- Documentation/git-tar-tree.txt | 4 +- Documentation/git-update-index.txt | 4 +- Documentation/git.txt | 45 ++++++++++++++---------- Documentation/gitcli.txt | 2 +- Documentation/howto/revert-branch-rebase.txt | 2 +- Documentation/pull-fetch-param.txt | 2 +- archive.c | 4 +- builtin/commit-tree.c | 15 +++++--- builtin/describe.c | 4 +- builtin/diff-index.c | 2 +- builtin/diff-tree.c | 2 +- builtin/diff.c | 2 +- builtin/ls-files.c | 4 +- builtin/ls-tree.c | 2 +- builtin/merge-index.c | 2 +- builtin/merge.c | 2 +- builtin/pack-objects.c | 2 +- builtin/push.c | 2 +- builtin/revert.c | 4 +- builtin/tar-tree.c | 2 +- contrib/examples/git-merge.sh | 2 +- contrib/examples/git-reset.sh | 2 +- contrib/examples/git-revert.sh | 4 +- fast-import.c | 16 ++++---- git-svn.perl | 2 +- remote.c | 4 +- t/t1101-commit-tree-indirect.sh | 49 ++++++++++++++++++++++++++ t/t4100/t-apply-3.patch | 8 ++-- t/t4100/t-apply-7.patch | 8 ++-- 56 files changed, 200 insertions(+), 144 deletions(-) create mode 100755 t/t1101-commit-tree-indirect.sh