Document gitattributes(5)

Signed-off-by: Junio C Hamano <junkio@cox.net>

diff --git a/Documentation/Makefile b/Documentation/Makefile
index f4c6a803c3107e05da2473da4de53d3f6bdb8090..8d3617db9772249a1e9d7bc242d7963672081acb 100644 (file)
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -2,7 +2,7 @@ MAN1_TXT= \
        $(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
                $(wildcard git-*.txt)) \
        gitk.txt
-MAN5_TXT=
+MAN5_TXT=gitattributes.txt
 MAN7_TXT=git.txt
 
 DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))
@@ -68,7 +68,7 @@ install: man
        $(INSTALL) -d -m755 $(DESTDIR)$(man5dir)
        $(INSTALL) -d -m755 $(DESTDIR)$(man7dir)
        $(INSTALL) -m644 $(DOC_MAN1) $(DESTDIR)$(man1dir)
-       : $(INSTALL) -m644 $(DOC_MAN5) $(DESTDIR)$(man5dir)
+       $(INSTALL) -m644 $(DOC_MAN5) $(DESTDIR)$(man5dir)
        $(INSTALL) -m644 $(DOC_MAN7) $(DESTDIR)$(man7dir)
 
 

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 7e41ca6a0d3e4329d1efc10b4dcb90613975e5bd..a130846883df1fb310325447f2b648f0979c4f70 100644 (file)
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -499,6 +499,19 @@ merge.verbosity::
        conflicts, 2 outputs conflicts and file changes.  Level 5 and
        above outputs debugging information.  The default is level 2.
 
+merge.<driver>.name::
+       Defines a human readable name for a custom low-level
+       merge driver.  See gitlink:gitattributes[5] for details.
+
+merge.<driver>.driver::
+       Defines the command that implements a custom low-level
+       merge driver.  See gitlink:gitattributes[5] for details.
+
+merge.<driver>.recursive::
+       Names a low-level merge driver to be used when
+       performing an internal merge between common ancestors.
+       See gitlink:gitattributes[5] for details.
+
 pack.window::
        The size of the window used by gitlink:git-pack-objects[1] when no
        window size is given on the command line. Defaults to 10.

diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
new file mode 100644 (file)
index 0000000..ece58ab
--- /dev/null
+++ b/Documentation/gitattributes.txt
@@ -0,0 +1,285 @@
+gitattributes(5)
+================
+
+NAME
+----
+gitattributes - defining attributes per path
+
+SYNOPSIS
+--------
+.gitattributes
+
+
+DESCRIPTION
+-----------
+
+A `gitattributes` file is a simple text file that gives
+`attributes` to pathnames.
+
+Each line in `gitattributes` file is of form:
+
+       glob    attr1 attr2 ...
+
+That is, a glob pattern followed by an attributes list,
+separated by whitespaces.  When the glob pattern matches the
+path in question, the attributes listed on the line are given to
+the path.
+
+Each attribute can be in one of these states for a given path:
+
+Set::
+
+       The path has the attribute with special value "true";
+       this is specified by listing only the name of the
+       attribute in the attribute list.
+
+Unset::
+
+       The path has the attribute with special value "false";
+       this is specified by listing the name of the attribute
+       prefixed with a dash `-` in the attribute list.
+
+Set to a value::
+
+       The path has the attribute with specified string value;
+       this is specified by listing the name of the attribute
+       followed by an equal sign `=` and its value in the
+       attribute list.
+
+Unspecified::
+
+       No glob pattern matches the path, and nothing says if
+       the path has or does not have the attribute.
+
+When more than one glob pattern matches the path, a later line
+overrides an earlier line.
+
+When deciding what attributes are assigned to a path, git
+consults `$GIT_DIR/info/attributes` file (which has the highest
+precedence), `.gitattributes` file in the same directory as the
+path in question, and its parent directories (the further the
+directory that contains `.gitattributes` is from the path in
+question, the lower its precedence).
+
+Sometimes you would need to override an setting of an attribute
+for a path to `unspecified` state.  This can be done by listing
+the name of the attribute prefixed with an exclamation point `!`.
+
+
+EFFECTS
+-------
+
+Certain operations by git can be influenced by assigning
+particular attributes to a path.  Currently, three operations
+are attributes-aware.
+
+Checking-out and checking-in
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The attribute `crlf` affects how the contents stored in the
+repository are copied to the working tree files when commands
+such as `git checkout` and `git merge` run.  It also affects how
+git stores the contents you prepare in the working tree in the
+repository upon `git add` and `git commit`.
+
+Set::
+
+       Setting the `crlf` attribute on a path is meant to mark
+       the path as a "text" file.  'core.autocrlf' conversion
+       takes place without guessing the content type by
+       inspection.
+
+Unset::
+
+       Unsetting the `crlf` attribute on a path is meant to
+       mark the path as a "binary" file.  The path never goes
+       through line endings conversion upon checkin/checkout.
+
+Unspecified::
+
+       Unspecified `crlf` attribute tells git to apply the
+       `core.autocrlf` conversion when the file content looks
+       like text.
+
+Set to string value "input"::
+
+       This is similar to setting the attribute to `true`, but
+       also forces git to act as if `core.autocrlf` is set to
+       `input` for the path.
+
+Any other value set to `crlf` attribute is ignored and git acts
+as if the attribute is left unspecified.
+
+
+The `core.autocrlf` conversion
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the configuration variable `core.autocrlf` is false, no
+conversion is done.
+
+When `core.autocrlf` is true, it means that the platform wants
+CRLF line endings for files in the working tree, and you want to
+convert them back to the normal LF line endings when checking
+in to the repository.
+
+When `core.autocrlf` is set to "input", line endings are
+converted to LF upon checkin, but there is no conversion done
+upon checkout.
+
+
+Generating diff text
+~~~~~~~~~~~~~~~~~~~~
+
+The attribute `diff` affects if `git diff` generates textual
+patch for the path or just says `Binary files differ`.
+
+Set::
+
+       A path to which the `diff` attribute is set is treated
+       as text, even when they contain byte values that
+       normally never appear in text files, such as NUL.
+
+Unset::
+
+       A path to which the `diff` attribute is unset will
+       generate `Binary files differ`.
+
+Unspecified::
+
+       A path to which the `diff` attribute is unspecified
+       first gets its contents inspected, and if it looks like
+       text, it is treated as text.  Otherwise it would
+       generate `Binary files differ`.
+
+Any other value set to `diff` attribute is ignored and git acts
+as if the attribute is left unspecified.
+
+
+Performing a three-way merge
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The attribute `merge` affects how three versions of a file is
+merged when a file-level merge is necessary during `git merge`,
+and other programs such as `git revert` and `git cherry-pick`.
+
+Set::
+
+       Built-in 3-way merge driver is used to merge the
+       contents in a way similar to `merge` command of `RCS`
+       suite.  This is suitable for ordinary text files.
+
+Unset::
+
+       Take the version from the current branch as the
+       tentative merge result, and declare that the merge has
+       conflicts.  This is suitable for binary files that does
+       not have a well-defined merge semantics.
+
+Unspecified::
+
+       By default, this uses the same built-in 3-way merge
+       driver as is the case the `merge` attribute is set.
+       However, `merge.default` configuration variable can name
+       different merge driver to be used for paths to which the
+       `merge` attribute is unspecified.
+
+Any other string value::
+
+       3-way merge is performed using the specified custom
+       merge driver.  The built-in 3-way merge driver can be
+       explicitly specified by asking for "text" driver; the
+       built-in "take the current branch" driver can be
+       requested by "binary".
+
+
+Defining a custom merge driver
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The definition of a merge driver is done in `gitconfig` not
+`gitattributes` file, so strictly speaking this manual page is a
+wrong place to talk about it.  However...
+
+To define a custom merge driver `filfre`, add a section to your
+`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
+
+----------------------------------------------------------------
+[merge "filfre"]
+       name = feel-free merge driver
+       driver = filfre %O %A %B
+       recursive = binary
+----------------------------------------------------------------
+
+The `merge.*.name` variable gives the driver a human-readable
+name.
+
+The `merge.*.driver` variable's value is used to construct a
+command to run to merge ancestor's version (`%O`), current
+version (`%A`) and the other branches' version (`%B`).  These
+three tokens are replaced with the names of temporary files that
+hold the contents of these versions when the command line is
+built.
+
+The merge driver is expected to leave the result of the merge in
+the file named with `%A` by overwriting it, and exit with zero
+status if it managed to merge them cleanly, or non-zero if there
+were conflicts.
+
+The `merge.*.recursive` variable specifies what other merge
+driver to use when the merge driver is called for an internal
+merge between common ancestors, when there are more than one.
+When left unspecified, the driver itself is used for both
+internal merge and the final merge.
+
+
+EXAMPLE
+-------
+
+If you have these three `gitattributes` file:
+
+----------------------------------------------------------------
+(in $GIT_DIR/info/attributes)
+
+a*     foo !bar -baz
+
+(in .gitattributes)
+abc    foo bar baz
+
+(in t/.gitattributes)
+ab*    merge=filfre
+abc    -foo -bar
+*.c    frotz
+----------------------------------------------------------------
+
+the attributes given to path `t/abc` are computed as follows:
+
+1. By examining `t/.gitattributes` (which is in the same
+   diretory as the path in question), git finds that the first
+   line matches.  `merge` attribute is set.  It also finds that
+   the second line matches, and attributes `foo` and `bar`
+   are unset.
+
+2. Then it examines `.gitattributes` (which is in the parent
+   directory), and finds that the first line matches, but
+   `t/.gitattributes` file already decided how `merge`, `foo`
+   and `bar` attributes should be given to this path, so it
+   leaves `foo` and `bar` unset.  Attribute `baz` is set.
+
+3. Finally it examines `$GIT_DIR/info/gitattributes`.  This file
+   is used to override the in-tree settings.  The first line is
+   a match, and `foo` is set, `bar` is reverted to unspecified
+   state, and `baz` is unset.
+
+As the result, the attributes assignement to `t/abc` becomes:
+
+----------------------------------------------------------------
+foo    set to true
+bar    unspecified
+baz    set to false
+merge  set to string value "filfre"
+frotz  unspecified
+----------------------------------------------------------------
+
+
+GIT
+---
+Part of the gitlink:git[7] suite