gitignore vs. exclude vs assume-unchanged?

gitignore vs. exclude vs assume-unchanged?

[alex]

Any clarification on the differences much appreciated:

http://stackoverflow.com/questions/23097368/git-ignore-vs-exclude-vs-assume-unchanged/23097509

Re: gitignore vs. exclude vs assume-unchanged?

[Junio C Hamano]

alex@bellandwhistle.net writes:

> Any clarification on the differences much appreciated:
>
> http://stackoverflow.com/questions/23097368/git-ignore-vs-exclude-vs-assume-unchanged/23097509

Please don't force people to refer to external site.

The .gitignore and .git/info/exclude are the two UIs to invoke the
same mechanism.  In-tree .gitignore are to be shared among project
members (i.e. everybody working on the project should consider the
paths that match the ignore pattern in there as cruft).  On the
other hand, .git/info/exclude is meant for personal ignore patterns
(i.e. you, while working on the project, consider them as cruft).

Assume-unchanged should not be abused for an ignore mechanism.  It
is "I know my filesystem operations are slow.  I'll promise Git that
I won't change these paths by making them with that bit---that way,
Git does not have to check if I changed things in there every time I
ask for 'git status' output".  It does not mean anything other than
that.  Especially, it is *not* a promise by Git that Git will always
consider these paths are unmodified---if Git can determine a path
that is marked as assume-unchanged has changed without incurring
extra lstat(2) cost, it reserves the right to report that the path
*has been* modified (as a result, "git commit -a" is free to commit
that change).

Re: gitignore vs. exclude vs assume-unchanged?

[alex]

On 2014-04-16 10:51, Junio C Hamano wrote:
> alex@bellandwhistle.net writes:
> 
>> Any clarification on the differences much appreciated:
>> 
>> http://stackoverflow.com/questions/23097368/git-ignore-vs-exclude-vs-assume-unchanged/23097509
> 
> Please don't force people to refer to external site.
> 
> The .gitignore and .git/info/exclude are the two UIs to invoke the
> same mechanism.  In-tree .gitignore are to be shared among project
> members (i.e. everybody working on the project should consider the
> paths that match the ignore pattern in there as cruft).  On the
> other hand, .git/info/exclude is meant for personal ignore patterns
> (i.e. you, while working on the project, consider them as cruft).
> 
> Assume-unchanged should not be abused for an ignore mechanism.  It
> is "I know my filesystem operations are slow.  I'll promise Git that
> I won't change these paths by making them with that bit---that way,
> Git does not have to check if I changed things in there every time I
> ask for 'git status' output".  It does not mean anything other than
> that.  Especially, it is *not* a promise by Git that Git will always
> consider these paths are unmodified---if Git can determine a path
> that is marked as assume-unchanged has changed without incurring
> extra lstat(2) cost, it reserves the right to report that the path
> *has been* modified (as a result, "git commit -a" is free to commit
> that change).

Thanks June. Great to hear this authoritatively.

IMHO your very helpful explanation about typical use cases, the purpose 
of 'exclude, and assume-unchanged not being a "promise" is missing from 
the docs, or at least not obviously present:

http://git-scm.com/docs

In particular, 'exclude' is spottily documented. I realize the docs are 
structured strictly as an API reference, but it would be great to see a 
comparison of ignore techniques spelled out. FWIW I asked several people 
I think of as experts and none of them felt sure of their answer. :)

thanks again.

Re: gitignore vs. exclude vs assume-unchanged?

[Jonathan Nieder]

Hi,

alex@bellandwhistle.net wrote:

> In particular, 'exclude' is spottily documented.

Where did you expect to read about it?  I see some mention of
.git/info/exclude in the gitignore(5) page, but I wouldn't be
surprised if there's room for improvement there (improvements
welcome).

>                                                  I realize the docs
> are structured strictly as an API reference,

No, the docs are meant to be helpful, not just to confirm what people
already know. ;-)

Thanks,
Jonathan

Re: gitignore vs. exclude vs assume-unchanged?

[alex]

On 2014-04-16 16:45, Jonathan Nieder wrote:
> Hi,
> 
> alex@bellandwhistle.net wrote:
> 
>> In particular, 'exclude' is spottily documented.
> 
> Where did you expect to read about it?  I see some mention of
> .git/info/exclude in the gitignore(5) page, but I wouldn't be
> surprised if there's room for improvement there (improvements
> welcome).

I suppose I might consider amending the opening sentence at:

http://git-scm.com/docs/gitignore

from:

"A gitignore file specifies intentionally untracked files that Git 
should ignore."

to something that makes the point earlier about the similarity:

"Both gitignore and $GIT_DIR/info/exclude files specify intentionally 
untracked files that Git should ignore."

or:

"Like the $GIT_DIR/info/exclude file, gitignore files specify 
intentionally untracked files that Git should ignore. The difference is 
that files matched by a pattern in a gitignore file will be untracked 
for all users of the repository."

or somesuch.

The other thing is that there is no warning in the docs that 
assume-unchanged is not an absolute promise to ignore. This is news to 
me. I don't see this anywhere. I understand now that the use case is 
performance, but that could be clearer.

thanks again
Alex

Re: gitignore vs. exclude vs assume-unchanged?

[Andrew Ardill]

On 18 April 2014 10:36,  <alex@bellandwhistle.net> wrote:
> "Like the $GIT_DIR/info/exclude file, gitignore files specify intentionally
> untracked files that Git should ignore. The difference is that files matched
> by a pattern in a gitignore file will be untracked for all users of the
> repository."

As a data point, I have seen people add ".gitignore" to their
.gitignore file, as they don't want to share the file.

This seems like a misuse of the functionality, as
$GIT_DIR/info/exclude is a better choice for the same use case, but
I'm not sure why the misuse is there.

My guess is that users aren't aware of excludes, whilst gitignore is
placed front of mind living at the root of many repositories.
Education will help here, but is there any way to make the 'correct'
way more intuitive?

It would be possible to check for this antipattern during normal use
and provide a hint to the user, but that is probably too heavy handed
and might annoy people with a legitimate use case. For that matter, if
the gitignore file is easier to use for the 'private ignore' use case
we have a bigger problem and shouldn't dictate to users what to use.

As to the documentation, it is already quite comprehensive. All
exclusion methods are listed, and the reasons for why to use them are
well laid out. The introduction does specifically mention 'gitignore'
files, but that seems to be due to all the ignore files
($HOME/.config/git/ignore, $GIT_DIR/info/exclude, .gitignore) being
classified as 'gitignore' files.

So some possible improvements. We could replace 'gitignore' with 'git
ignore' in instances where we are referencing all forms of the ignore
file, not just the .gitignore file.

"Git ignore files specify intentionally untracked files that Git should ignore."

We could reference the multiple ignore locations earlier, for people
who don't read past the first paragraph of to documentation.

"Git ignore files specify intentionally untracked files that Git
should ignore. A git ignore file can be specified for all local
repositories, a specific local repository, or shared with other users
of a repository. Files already tracked by Git are not affected; see
the NOTES below for details."

Finally, it's a little confusing that one of the files is called 'exclude'.

It would be great to rename it to 'ignore'; $GIT_DIR/info/exclude ->
$GIT_DIR/info/ignore. Is there any reason this shouldn't be done?
I haven't checked how extensive a change this would need be, but it
would make the usage much more consistent. The only reference I have
found to this file is at http://markmail.org/message/l7shxticxo3kzdpn
from Junio in a discussion around an RFD for ignore rules.

I think these three changes together would make the intended usage
more obvious to both new and old users, though each change could stand
on its own as well.

Regards,

Andrew Ardill

Re: gitignore vs. exclude vs assume-unchanged?

[Junio C Hamano]

Andrew Ardill <andrew.ardill@gmail.com> writes:

> As a data point, I have seen people add ".gitignore" to their
> .gitignore file, as they don't want to share the file.

Interesting.  It will break immediately when the project starts
wanting to distribute its "canonical" ignore list, but until that
time, it would "work" (for some definition of "working").

> It would be possible to check for this antipattern during normal use
> and provide a hint to the user, but that is probably too heavy handed
> and might annoy people with a legitimate use case. For that matter, if
> the gitignore file is easier to use for the 'private ignore' use case
> we have a bigger problem and shouldn't dictate to users what to use.

Very true.

> ... The introduction does specifically mention 'gitignore'
> files, but that seems to be due to all the ignore files
> ($HOME/.config/git/ignore, $GIT_DIR/info/exclude, .gitignore) being
> classified as 'gitignore' files.

Yes.  Notice that that the blanket term used is not "dot-gitignore",
but "gitignore".  The difference may be too subtle, and your
suggestion to introduce a new phrase "git ignore files" as the
blanket term might be one way to make it less subtle.  I would
actually think "ignore files" (without Git, as all readers know we
are talking about _our_ ignore mechanism in our documentation) may
even be a better idea. 

> We could reference the multiple ignore locations earlier, for people
> who don't read past the first paragraph of to documentation.
>
> "Git ignore files specify intentionally untracked files that Git
> should ignore. A git ignore file can be specified for all local
> repositories, a specific local repository, or shared with other users
> of a repository. Files already tracked by Git are not affected; see
> the NOTES below for details."

Sounds good, with or without s/git ignore/ignore/.

> Finally, it's a little confusing that one of the files is called 'exclude'.
>
> It would be great to rename it to 'ignore'; $GIT_DIR/info/exclude ->
> $GIT_DIR/info/ignore. Is there any reason this shouldn't be done?

If we were starting Git from scratch, we may have called it
info/ignore, but we do not live in an ideal world, so we need to
worry about people's existing repositories, scripts and templates.

That does not mean we cannot transition over time, aiming to flip
the default in a future big version bump (no, not in 2.0), along the
lines of (note: I haven't thought this thru, and do not take this as
an authoritative and correct plan):

  Step 1.

   - Check if info/ignore exists, and read it without reading or
     even checking the existence of info/exclude;

   - Check if info/exclude exists, and read it.  Warn about future
     default change and tell the user to rename (or if we are
     absolutely sure that we are interactive, we can offer to do the
     rename for the user by prompting).

  Step 2.

   - Wait for several major releases, until major distros catch up
     with step 1.

  Step 3.

   - Drop the support for info/exclude altogether, without even
     warning about our stopping to read it.

Re: gitignore vs. exclude vs assume-unchanged?

[alex]

> Andrew Ardill <andrew.ardill@gmail.com> writes:
> 
> As a data point, I have seen people add ".gitignore" to their
> .gitignore file, as they don't want to share the file.

Right, I've seen that too. It confused the heck out of me. It only lends 
credence to my point about the docs. Those users want the functionality 
of a pattern in '$GIT_DIR/info/exclude', but haven't been able to figure 
it out easily enough. They've just heard about .gitignore, so they're 
using that. Yes, it's all there in the docs if you read it several 
times, and you already know what you're looking at, but not in a 
terribly accessible, best practices, "advice from a smart friend who's 
been through it all already" kind of way.

> ... The introduction does specifically mention 'gitignore'
> files, but that seems to be due to all the ignore files
> ($HOME/.config/git/ignore, $GIT_DIR/info/exclude, .gitignore) being
> classified as 'gitignore' files.

Yes, the 'gitignore' versus '.gitignore' distinction is hopelessly 
subtle. It is very easy for a newcomer to think these are exactly the 
same thing. I certainly did.

> Finally, it's a little confusing that one of the files is called 
> 'exclude'.
> 
> It would be great to rename it to 'ignore'; $GIT_DIR/info/exclude ->
> $GIT_DIR/info/ignore. Is there any reason this shouldn't be done?

Well, yes: semantics. Since they do slightly different things, they 
should have different names. It makes reference and teaching much 
easier. In fact, if a renaming were to occur, I would actually prefer 
even better semantics:

     .gitignore -> .shared-ignore

     $GIT_DIR/info/exclude -> $GIT_DIR/info/local-ignore

These suggested names could perhaps be improved on. But if anything, the 
names need to be more different, not less. Users should be able to 
instantly know what a speaker is talking about without having to 
doublecheck and ask if by "git-ignore", the speaker really meant "git 
ignore" or "dot-gitignore".

Thanks,
Alex

Re: gitignore vs. exclude vs assume-unchanged?

[luc.linux]

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

On Fri, Apr 25, 2014 at 04:09:47PM -0700, alex@bellandwhistle.net wrote:
> >Andrew Ardill <andrew.ardill@gmail.com> writes:
> >
> >As a data point, I have seen people add ".gitignore" to their
> >.gitignore file, as they don't want to share the file.
> 
> Right, I've seen that too.
That something I am actually doing in my projects, because I didn't
know they were other way to exclude files like .gitignore.

> It confused the heck out of me. It only lends
> credence to my point about the docs. Those users want the functionality of a
> pattern in '$GIT_DIR/info/exclude', but haven't been able to figure it out
> easily enough. They've just heard about .gitignore, so they're using that.
> Yes, it's all there in the docs if you read it several times, and you
> already know what you're looking at, but not in a terribly accessible, best
> practices, "advice from a smart friend who's been through it all already"
> kind of way.
 Well documentation can be useful when you know what you're looking for,
 but I won't go read it just for discovering new features I didn't know.

> Well, yes: semantics. Since they do slightly different things, they should
> have different names. It makes reference and teaching much easier. In fact,
> if a renaming were to occur, I would actually prefer even better semantics:
> 
>     .gitignore -> .shared-ignore
> 
>     $GIT_DIR/info/exclude -> $GIT_DIR/info/local-ignore
> 
> These suggested names could perhaps be improved on. But if anything, the
> names need to be more different, not less. Users should be able to instantly
> know what a speaker is talking about without having to doublecheck and ask
> if by "git-ignore", the speaker really meant "git ignore" or
> "dot-gitignore".
I agree with a new name for .gitignore. A name like shared-ignore would
make explicite the fact it is shared, and then the user would look for
another way to locally exclude files. This would be a good approach, but
changing it won't be easy as most people already use .gitignore.

Would it be acceptable to have git display a warning when it detects
that .gitignore is excluding itself, with eventually a link to the
documentation or the path to $GIT_DIR/info/exclude ?


[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]

Re: gitignore vs. exclude vs assume-unchanged?

[Zé]

On 04/22/2014 06:54 PM, Junio C Hamano wrote:
> Interesting.  It will break immediately when the project starts
> wanting to distribute its "canonical" ignore list

If that happens, that's a problem caused by the project wanting to 
misuse .gitignore.

There are good practices and bad practices.  Forcing a common .gitignore 
upon everyone with access to the source code is not a good practice.

-- 
Zé