development/git
development/git
1
0
Fork 0
mirror of https://github.com/git/git synced 2024-10-30 14:03:28 +00:00
Code Issues Projects Releases Packages Wiki Activity
git/Documentation/git-check-attr.txt

126 lines
3.3 KiB
Text
Raw Normal View History

Document git-check-attr Signed-off-by: James Bowes <jbowes@dangerouslyinc.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-04-15 01:27:20 +00:00
git-check-attr(1)
=================
NAME
----
Remove the period after the git-check-attr summary The period at the end of the git-check-attr summary causes there to be two periods after the summary in the git(1) manual page. Signed-off-by: Matt Kraai <kraai@ftbfs.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-11-07 12:26:55 +00:00
git-check-attr - Display gitattributes information
Document git-check-attr Signed-off-by: James Bowes <jbowes@dangerouslyinc.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-04-15 01:27:20 +00:00
SYNOPSIS
--------
git-check-attr(1): use 'verse' for multi-line synopsis sections Signed-off-by: Jonas Fonseca <fonseca@diku.dk> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-10-15 07:11:52 +00:00
[verse]
attr: add flag `--source` to work with tree-ish The contents of the .gitattributes files may evolve over time, but "git check-attr" always checks attributes against them in the working tree and/or in the index. It may be beneficial to optionally allow the users to check attributes taken from a commit other than HEAD against paths. Add a new flag `--source` which will allow users to check the attributes against a commit (actually any tree-ish would do). When the user uses this flag, we go through the stack of .gitattributes files but instead of checking the current working tree and/or in the index, we check the blobs from the provided tree-ish object. This allows the command to also be used in bare repositories. Since we use a tree-ish object, the user can pass "--source HEAD:subdirectory" and all the attributes will be looked up as if subdirectory was the root directory of the repository. We cannot simply use the `<rev>:<path>` syntax without the `--source` flag, similar to how it is used in `git show` because any non-flag parameter before `--` is treated as an attribute and any parameter after `--` is treated as a pathname. The change involves creating a new function `read_attr_from_blob`, which given the path reads the blob for the path against the provided source and parses the attributes line by line. This function is plugged into `read_attr()` function wherein we go through the stack of attributes files. Signed-off-by: Karthik Nayak <karthik.188@gmail.com> Signed-off-by: Toon Claes <toon@iotcl.com> Co-authored-by: toon@iotcl.com Signed-off-by: Junio C Hamano <gitster@pobox.com>
2023-01-14 08:30:38 +00:00
'git check-attr' [--source <tree-ish>] [-a | --all | <attr>...] [--] <pathname>...
'git check-attr' --stdin [-z] [--source <tree-ish>] [-a | --all | <attr>...]
Document git-check-attr Signed-off-by: James Bowes <jbowes@dangerouslyinc.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-04-15 01:27:20 +00:00
DESCRIPTION
-----------
Documentation: minor grammatical fixes in git-check-attr.txt Signed-off-by: David J. Mellor <dmellor@whistlingcat.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-23 01:00:16 +00:00
For every pathname, this command will list if each attribute is 'unspecified',
Document git-check-attr Signed-off-by: James Bowes <jbowes@dangerouslyinc.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-04-15 01:27:20 +00:00
'set', or 'unset' as a gitattribute on that pathname.
OPTIONS
-------
git-check-attr: Add an --all option to show all attributes Add new usage patterns git check-attr [-a | --all] [--] pathname... git check-attr --stdin [-a | --all] < <list-of-paths> which display all attributes associated with the specified file(s). Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-08-04 04:36:30 +00:00
-a, --all::
List all attributes that are associated with the specified
paths. If this option is used, then 'unspecified' attributes
will not be included in the output.
Teach '--cached' option to check-attr This option causes check-attr to consider .gitattributes only from the index, ignoring .gitattributes from the working tree. This allows the command to be used in situations where a working tree does not exist. Signed-off-by: Jay Soffian <jaysoffian@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-09-22 21:44:20 +00:00
--cached::
Consider `.gitattributes` in the index only, ignoring the working tree.
check-attr: Add --stdin option This allows multiple paths to be specified on stdin. Signed-off-by: Dmitry Potapov <dpotapov@gmail.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2008-10-07 00:16:52 +00:00
--stdin::
usage: do not insist that standard input must come from a file The synopsys text and the usage string of subcommands that read list of things from the standard input are often shown like this: git gostak [--distim] < <list-of-doshes> This is problematic in a number of ways: * The way to use these commands is more often to feed them the output from another command, not feed them from a file. * Manual pages outside Git, commands that operate on the data read from the standard input, e.g "sort", "grep", "sed", etc., are not described with such a "< redirection-from-file" in their synopsys text. Our doing so introduces inconsistency. * We do not insist on where the output should go, by saying git gostak [--distim] < <list-of-doshes> > <output> * As it is our convention to enclose placeholders inside <braket>, the redirection operator followed by a placeholder filename becomes very hard to read, both in the documentation and in the help text. Let's clean them all up, after making sure that the documentation clearly describes the modes that take information from the standard input and what kind of things are expected on the input. [jc: stole example for fmt-merge-msg from Jonathan] Helped-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-10-16 18:27:42 +00:00
Read pathnames from the standard input, one per line,
instead of from the command-line.
check-attr: Add --stdin option This allows multiple paths to be specified on stdin. Signed-off-by: Dmitry Potapov <dpotapov@gmail.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2008-10-07 00:16:52 +00:00
-z::
Documentation: fix a bunch of typos, both old and new Reported-by: Jens Schleusener <Jens.Schleusener@fossies.org> Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-11-05 17:07:20 +00:00
The output format is modified to be machine-parsable.
check-attr -z: a single -z should apply to both input and output Unless a command has separate --nul-terminated-{input,output} options, the --nul-terminated-records (-z) option should apply to both input and output for consistency. The caller knows that its input paths may need to be protected for LF, and the program shows these problematic paths to its output. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-07-12 06:02:40 +00:00
If `--stdin` is also given, input paths are separated
with a NUL character instead of a linefeed character.
check-attr: Add --stdin option This allows multiple paths to be specified on stdin. Signed-off-by: Dmitry Potapov <dpotapov@gmail.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
2008-10-07 00:16:52 +00:00
attr: add flag `--source` to work with tree-ish The contents of the .gitattributes files may evolve over time, but "git check-attr" always checks attributes against them in the working tree and/or in the index. It may be beneficial to optionally allow the users to check attributes taken from a commit other than HEAD against paths. Add a new flag `--source` which will allow users to check the attributes against a commit (actually any tree-ish would do). When the user uses this flag, we go through the stack of .gitattributes files but instead of checking the current working tree and/or in the index, we check the blobs from the provided tree-ish object. This allows the command to also be used in bare repositories. Since we use a tree-ish object, the user can pass "--source HEAD:subdirectory" and all the attributes will be looked up as if subdirectory was the root directory of the repository. We cannot simply use the `<rev>:<path>` syntax without the `--source` flag, similar to how it is used in `git show` because any non-flag parameter before `--` is treated as an attribute and any parameter after `--` is treated as a pathname. The change involves creating a new function `read_attr_from_blob`, which given the path reads the blob for the path against the provided source and parses the attributes line by line. This function is plugged into `read_attr()` function wherein we go through the stack of attributes files. Signed-off-by: Karthik Nayak <karthik.188@gmail.com> Signed-off-by: Toon Claes <toon@iotcl.com> Co-authored-by: toon@iotcl.com Signed-off-by: Junio C Hamano <gitster@pobox.com>
2023-01-14 08:30:38 +00:00
--source=<tree-ish>::
Check attributes against the specified tree-ish. It is common to
specify the source tree by naming a commit, branch or tag associated
with it.
Document git-check-attr Signed-off-by: James Bowes <jbowes@dangerouslyinc.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-04-15 01:27:20 +00:00
\--::
Documentation: minor grammatical fixes in git-check-attr.txt Signed-off-by: David J. Mellor <dmellor@whistlingcat.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-23 01:00:16 +00:00
Interpret all preceding arguments as attributes and all following
git-check-attr: Fix command-line handling to match docs According to the git-check-attr synopsis, if the '--stdin' option is used then no pathnames are expected on the command line. Change the behavior to match this description; namely, if '--stdin' is used but not '--', then treat all command-line arguments as attribute names. Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-08-04 04:36:32 +00:00
arguments as path names.
If none of `--stdin`, `--all`, or `--` is used, the first argument
will be treated as an attribute and the rest of the arguments as
pathnames.
Document git-check-attr Signed-off-by: James Bowes <jbowes@dangerouslyinc.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-04-15 01:27:20 +00:00
git-check-attr(1): add output and example sections Plumbing tools should document what output can be expected. Signed-off-by: Jonas Fonseca <fonseca@diku.dk> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-10-15 07:10:58 +00:00
OUTPUT
------
The output is of the form:
<path> COLON SP <attribute> COLON SP <info> LF
check-attr -z: a single -z should apply to both input and output Unless a command has separate --nul-terminated-{input,output} options, the --nul-terminated-records (-z) option should apply to both input and output for consistency. The caller knows that its input paths may need to be protected for LF, and the program shows these problematic paths to its output. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-07-12 06:02:40 +00:00
unless `-z` is in effect, in which case NUL is used as delimiter:
<path> NUL <attribute> NUL <info> NUL
Documentation: minor grammatical fixes in git-check-attr.txt Signed-off-by: David J. Mellor <dmellor@whistlingcat.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-23 01:00:16 +00:00
<path> is the path of a file being queried, <attribute> is an attribute
git-check-attr(1): add output and example sections Plumbing tools should document what output can be expected. Signed-off-by: Jonas Fonseca <fonseca@diku.dk> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-10-15 07:10:58 +00:00
being queried and <info> can be either:
'unspecified';; when the attribute is not defined for the path.
Documentation: minor grammatical fixes in git-check-attr.txt Signed-off-by: David J. Mellor <dmellor@whistlingcat.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-23 01:00:16 +00:00
'unset';; when the attribute is defined as false.
'set';; when the attribute is defined as true.
git-check-attr(1): add output and example sections Plumbing tools should document what output can be expected. Signed-off-by: Jonas Fonseca <fonseca@diku.dk> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-10-15 07:10:58 +00:00
<value>;; when a value has been assigned to the attribute.
Documentation: add caveats about I/O buffering for check-{attr,ignore} check-attr and check-ignore have the potential to deadlock callers which do not read back the output in real-time. For example, if a caller writes N paths out and then reads N lines back in, it risks becoming blocked on write() to check-*, and check-* is blocked on write back to the caller. Somebody has to buffer; the pipe buffers provide some leeway, but they are limited. Thanks to Peff for pointing this out: http://article.gmane.org/gmane.comp.version-control.git/220534 Signed-off-by: Adam Spiers <git@adamspiers.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-04-11 12:05:13 +00:00
Buffering happens as documented under the `GIT_FLUSH` option in
linkgit:git[1]. The caller is responsible for avoiding deadlocks
caused by overfilling an input buffer or reading from an empty output
buffer.
git-check-attr(1): add output and example sections Plumbing tools should document what output can be expected. Signed-off-by: Jonas Fonseca <fonseca@diku.dk> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-10-15 07:10:58 +00:00
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
---------------
git-check-attr: Add an --all option to show all attributes Add new usage patterns git check-attr [-a | --all] [--] pathname... git check-attr --stdin [-a | --all] < <list-of-paths> which display all attributes associated with the specified file(s). Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-08-04 04:36:30 +00:00
* Listing all attributes for a file:
---------------
$ git check-attr --all -- org/example/MyClass.java
org/example/MyClass.java: diff: java
org/example/MyClass.java: myAttr: set
---------------
Documentation: minor grammatical fixes in git-check-attr.txt Signed-off-by: David J. Mellor <dmellor@whistlingcat.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-23 01:00:16 +00:00
* Listing an attribute for multiple files:
git-check-attr(1): add output and example sections Plumbing tools should document what output can be expected. Signed-off-by: Jonas Fonseca <fonseca@diku.dk> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-10-15 07:10:58 +00:00
---------------
$ 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
---------------
Document git-check-attr Signed-off-by: James Bowes <jbowes@dangerouslyinc.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-04-15 01:27:20 +00:00
Documentation: describe 'union' low-level merge driver Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-23 07:14:59 +00:00
SEE ALSO
--------
Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-29 06:20:38 +00:00
linkgit:gitattributes[5].
Documentation: describe 'union' low-level merge driver Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-23 07:14:59 +00:00
Document git-check-attr Signed-off-by: James Bowes <jbowes@dangerouslyinc.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-04-15 01:27:20 +00:00
GIT
---
documentation: move git(7) to git(1) As the "git" man page describes the "git" command at the end-user level, it seems better to move it to man section 1. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-06 07:07:32 +00:00
Part of the linkgit:git[1] suite
Reference in a new issue Copy permalink