Improve and fix git-check-attr(1)
PATCH 1/1 Improve and fix git-check-attr(1)
Always use 'verse' for multi-line synopsis sections. Add output and example sections to document what output can be expected.
--- Documentation/git-check-attr.txt | 63 +++++++++++++++++++++++++++++++++++++- 1 files changed, 62 insertions(+), 1 deletions(-)
At least the first chunk should be applied. The last is a quick attempt at documenting the expected output formally and with examples.
Documentation/git-check-attr.txt +62 -1
@@ -8,8 +8,9 @@ git-check-attr - Display gitattributes information. SYNOPSIS -------- +[verse] 'git check-attr' attr... [--] pathname... -'git check-attr' --stdin [-z] attr... < <list-of-paths +'git check-attr' --stdin [-z] attr... < <list-of-paths> DESCRIPTION -----------
@@ -30,6 +31,66 @@ OPTIONS arguments as path names. If not supplied, only the first argument will be treated as an attribute. +OUTPUT +------ + +The output is of the form: +<path> COLON SP <attribute> COLON SP <info> LF + +Where <path> is the path of a file being queried, <attribute> is an attribute +being queried and <info> can be either: + +'unspecified';; when the attribute is not defined for the path. +'unset';; when the attribute is defined to false. +'set';; when the attribute is defined to true. +<value>;; when a value has been assigned to the attribute. + +EXAMPLES +-------- + +In the following examples, the following '.gitattributes' file is used: +--------------- +*.java diff=java -crlf myAttr +README caveat=unspecified +--------------- + +* Output for an unspecified attribute: +--------------- +$ git check-attr filter src/org/example/lib/MyClass.java +src/org/example/lib/MyClass.java: filter: unspecified +--------------- + +* Output for an unset attribute: +--------------- +$ git check-attr crlf src/org/example/lib/MyClass.java +src/org/example/lib/MyClass.java: crlf: unset +--------------- + +* Output for an attribute that has been set: +--------------- +$ git check-attr myAttr src/org/example/lib/MyClass.java +src/org/example/lib/MyClass.java: myAttr: set +--------------- + +* Output for an attribute set to a value: +--------------- +$ git check-attr diff src/org/example/lib/MyClass.java +src/org/example/lib/MyClass.java: diff: java +--------------- + +* Listing multiple attributes for a file: +--------------- +$ git check-attr crlf diff myAttr -- src/org/example/lib/MyClass.java +src/org/example/lib/MyClass.java: crlf: unset +src/org/example/lib/MyClass.java: diff: java +src/org/example/lib/MyClass.java: myAttr: set +--------------- + +* Not all values are equally unambiguous: +--------------- +$ git check-attr caveat README +src/org/example/lib/MyClass.java: caveat: unspecified +--------------- SEE ALSO --------
Signature · 4 lines
tg: (340fcf4..) jf/man-git-check-attr (depends on: next) -- Jonas Fonseca
Quoted 5 lines · Jonas Fonseca
Always use 'verse' for multi-line synopsis sections. Add output and example sections to document what output can be expected.
Signed-off-by Jonas Fonseca <[email protected]>
Quoted 8 lines
--- Documentation/git-check-attr.txt | 63 +++++++++++++++++++++++++++++++++++++- 1 files changed, 62 insertions(+), 1 deletions(-)At least the first chunk should be applied. The last is a quick attempt at documenting the expected output formally and with examples.
...
tg: (340fcf4..) jf/man-git-check-attr (depends on: next)
Should this really have to depend on next? I have a feeling that a large part of this (sans --stdin/-z) is a 'maint' material.
Could you split this into two patches, one for 'maint' to describe the output format, and another for 'next' (or 'dp/checkattr') to update the SYNOPSIS part?
PATCH 1/2 git-check-attr(1): add output and example sections
Plumbing tools should document what output can be expected.
--- Documentation/git-check-attr.txt | 50 ++++++++++++++++++++++++++++++++++++++ 1 files changed, 50 insertions(+), 0 deletions(-)
Junio C Hamano <[email protected]> wrote Tue, Oct 14, 2008:
Quoted 1 line
Should this really have to depend on next?
This is just topgit listing the patch dependencies.
Quoted 3 lines
Could you split this into two patches, one for 'maint' to describe the output format, and another for 'next' (or 'dp/checkattr') to update the SYNOPSIS part?
Done. The example has been updated to also show '!' in action.
Documentation/git-check-attr.txt +50 -0
@@ -22,6 +22,56 @@ OPTIONS arguments as path names. If not supplied, only the first argument will be treated as an attribute. +OUTPUT +------ + +The output is of the form: +<path> COLON SP <attribute> COLON SP <info> LF + +Where <path> is the path of a file being queried, <attribute> is an attribute +being queried and <info> can be either: + +'unspecified';; when the attribute is not defined for the path. +'unset';; when the attribute is defined to false. +'set';; when the attribute is defined to true. +<value>;; when a value has been assigned to the attribute. + +EXAMPLES +-------- + +In the examples, the following '.gitattributes' file is used: +--------------- +*.java diff=java -crlf myAttr +NoMyAttr.java !myAttr +README caveat=unspecified +--------------- + +* Listing a single attribute: +--------------- +$ git check-attr diff org/example/MyClass.java +org/example/MyClass.java: diff: java +--------------- + +* Listing multiple attributes for a file: +--------------- +$ git check-attr crlf diff myAttr -- org/example/MyClass.java +org/example/MyClass.java: crlf: unset +org/example/MyClass.java: diff: java +org/example/MyClass.java: myAttr: set +--------------- + +* Listing attribute for multiple files: +--------------- +$ git check-attr myAttr -- org/example/MyClass.java org/example/NoMyAttr.java +org/example/MyClass.java: myAttr: set +org/example/NoMyAttr.java: myAttr: unspecified +--------------- + +* Not all values are equally unambiguous: +--------------- +$ git check-attr caveat README +README: caveat: unspecified +--------------- SEE ALSO --------
Signature · 4 lines
tg: (6c16792..) jf/man-git-check-attr-output (depends on: maint) -- Jonas Fonseca
PATCH 2/2 git-check-attr(1): use 'verse' for multi-line synopsis sections
In reply to Junio C Hamano--- Documentation/git-check-attr.txt | 3 ++- 1 files changed, 2 insertions(+), 1 deletions(-)
Documentation/git-check-attr.txt +2 -1
@@ -8,8 +8,9 @@ git-check-attr - Display gitattributes information. SYNOPSIS -------- +[verse] 'git check-attr' attr... [--] pathname... -'git check-attr' --stdin [-z] attr... < <list-of-paths +'git check-attr' --stdin [-z] attr... < <list-of-paths> DESCRIPTION -----------
Signature · 4 lines
tg: (34458dd..) jf/man-git-check-attr-synopsis (depends on: jf/man-git-check-attr-output next) -- Jonas Fonseca