[PATCH] Add notes that some $GIT_DIR/info/ files are not copied by clone, etc.

[PATCH] Add notes that some $GIT_DIR/info/ files are not copied by clone, etc.

[Toby Corkindale]

[-- Attachment #1: Type: text/plain, Size: 0 bytes --]



[-- Attachment #2: 0001-Add-notes-that-GIT_DIR-info-files-are-not-copied-b.patch --]
[-- Type: text/x-patch, Size: 1558 bytes --]

---
 Documentation/gitattributes.txt |    4 ++++
 Documentation/gitignore.txt     |    3 +++
 2 files changed, 7 insertions(+), 0 deletions(-)

diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 84ec962..b3b497b 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -63,6 +63,10 @@ path in question, and its parent directories (the further the
 directory that contains `.gitattributes` is from the path in
 question, the lower its precedence).
 
+The $GIT_DIR/info/attributes file is used when you wish to only affect certain
+repositories. It will not be copied to other repositories by automatic
+operations such as clone, fetch, etc.
+
 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 `!`.
diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index e847b3b..435f23c 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -34,6 +34,9 @@ precedence, the last matching pattern decides the outcome):
    files generated as part of the project build.
 
  * Patterns read from `$GIT_DIR/info/exclude`.
+ * The $GIT_DIR/info/exclude file is used when you wish to only affect
+   certain repositories. It will not be copied to other repositories by
+   automatic operations such as clone, fetch, etc.
 
  * Patterns read from the file specified by the configuration
    variable 'core.excludesfile'.
-- 
1.5.4.3

Re: [PATCH] Add notes that some $GIT_DIR/info/ files are not copied by clone, etc.

[Jeff King]

On Thu, Mar 27, 2008 at 03:36:58PM +1100, Toby Corkindale wrote:

> ---
>  Documentation/gitattributes.txt |    4 ++++
>  Documentation/gitignore.txt     |    3 +++
>  2 files changed, 7 insertions(+), 0 deletions(-)

Generally git patches should be:

  - included inline rather than attached (it looks like you are using
    Thunderbird, which does have some whitespace munging issues; there
    is a section in SubmittingPatches that discusses Thunderbird
    specifically)

  - signed-off (see SubmittingPatches)

Comments on the content are below.

> diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
> index 84ec962..b3b497b 100644
> --- a/Documentation/gitattributes.txt
> +++ b/Documentation/gitattributes.txt
> @@ -63,6 +63,10 @@ path in question, and its parent directories (the further the
>  directory that contains `.gitattributes` is from the path in
>  question, the lower its precedence).
>  
> +The $GIT_DIR/info/attributes file is used when you wish to only affect certain
> +repositories. It will not be copied to other repositories by automatic
> +operations such as clone, fetch, etc.
> +

I think this paragraph is OK, and in a reasonable spot. Though it might
read easier for a user if it is inside-out from what you have written.
IOW, you have "X does Y" but I wonder if "if you want Y, then use X"
might be a better wording. See below.

> --- a/Documentation/gitignore.txt
> +++ b/Documentation/gitignore.txt
> @@ -34,6 +34,9 @@ precedence, the last matching pattern decides the outcome):
>     files generated as part of the project build.
>  
>   * Patterns read from `$GIT_DIR/info/exclude`.
> + * The $GIT_DIR/info/exclude file is used when you wish to only affect
> +   certain repositories. It will not be copied to other repositories by
> +   automatic operations such as clone, fetch, etc.
>  
>   * Patterns read from the file specified by the configuration
>     variable 'core.excludesfile'.

I don't like this one. There are actually _three_ different
places you can put ignore patterns, so I think you do better to wait
until after the precedence list is finished, and then discuss the
reasons for using each. How about this instead of your second hunk?

-- >8 --
Documentation: clarify differences between gitignore files

Since gitignore patterns can be read from three different
files, let's provide some hints to the user about how they
are typically used.

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/gitignore.txt |   12 ++++++++++++
 1 files changed, 12 insertions(+), 0 deletions(-)

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index e847b3b..613dca0 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -38,6 +38,18 @@ precedence, the last matching pattern decides the outcome):
  * Patterns read from the file specified by the configuration
    variable 'core.excludesfile'.
 
+Which file to place a pattern in depends on how the pattern is meant to
+be used. Patterns which should be version-controlled and distributed to
+other repositories via clone (i.e., files that all developers will want
+to ignore) should go into a `.gitignore` file. Patterns which are
+specific to a particular repository but which do not need to be shared
+with other related repositories (e.g., auxiliary files that live inside
+the repository but are specific to one user's workflow) should go into
+the `$GIT_DIR/info/exclude` file.  Patterns which a user wants git to
+ignore in all situations (e.g., backup or temporary files generated by
+the user's editor of choice) generally go into a file specified by
+`core.excludesfile` in the user's `~/.gitconfig`.
+
 The underlying git plumbing tools, such as
 linkgit:git-ls-files[1] and linkgit:git-read-tree[1], read
 `gitignore` patterns specified by command-line options, or from
-- 
1.5.5.rc1.133.g360d