* gitignore vs. exclude vs assume-unchanged? @ 2014-04-16 16:33 alex 2014-04-16 17:51 ` Junio C Hamano 0 siblings, 1 reply; 10+ messages in thread From: alex @ 2014-04-16 16:33 UTC (permalink / raw) To: git Any clarification on the differences much appreciated: http://stackoverflow.com/questions/23097368/git-ignore-vs-exclude-vs-assume-unchanged/23097509 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: gitignore vs. exclude vs assume-unchanged? 2014-04-16 16:33 gitignore vs. exclude vs assume-unchanged? alex @ 2014-04-16 17:51 ` Junio C Hamano 2014-04-16 23:07 ` alex 0 siblings, 1 reply; 10+ messages in thread From: Junio C Hamano @ 2014-04-16 17:51 UTC (permalink / raw) To: alex; +Cc: git 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). ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: gitignore vs. exclude vs assume-unchanged? 2014-04-16 17:51 ` Junio C Hamano @ 2014-04-16 23:07 ` alex 2014-04-16 23:45 ` Jonathan Nieder 0 siblings, 1 reply; 10+ messages in thread From: alex @ 2014-04-16 23:07 UTC (permalink / raw) To: Junio C Hamano; +Cc: git 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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: gitignore vs. exclude vs assume-unchanged? 2014-04-16 23:07 ` alex @ 2014-04-16 23:45 ` Jonathan Nieder 2014-04-18 0:36 ` alex 0 siblings, 1 reply; 10+ messages in thread From: Jonathan Nieder @ 2014-04-16 23:45 UTC (permalink / raw) To: alex; +Cc: Junio C Hamano, git 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: gitignore vs. exclude vs assume-unchanged? 2014-04-16 23:45 ` Jonathan Nieder @ 2014-04-18 0:36 ` alex 2014-04-22 0:40 ` Andrew Ardill 0 siblings, 1 reply; 10+ messages in thread From: alex @ 2014-04-18 0:36 UTC (permalink / raw) To: Jonathan Nieder; +Cc: Junio C Hamano, git 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: gitignore vs. exclude vs assume-unchanged? 2014-04-18 0:36 ` alex @ 2014-04-22 0:40 ` Andrew Ardill 2014-04-22 17:54 ` Junio C Hamano 0 siblings, 1 reply; 10+ messages in thread From: Andrew Ardill @ 2014-04-22 0:40 UTC (permalink / raw) To: alex; +Cc: Jonathan Nieder, Junio C Hamano, git@vger.kernel.org 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: gitignore vs. exclude vs assume-unchanged? 2014-04-22 0:40 ` Andrew Ardill @ 2014-04-22 17:54 ` Junio C Hamano 2014-04-25 23:09 ` alex 2014-04-26 12:26 ` Zé 0 siblings, 2 replies; 10+ messages in thread From: Junio C Hamano @ 2014-04-22 17:54 UTC (permalink / raw) To: Andrew Ardill; +Cc: alex, Jonathan Nieder, git@vger.kernel.org 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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: gitignore vs. exclude vs assume-unchanged? 2014-04-22 17:54 ` Junio C Hamano @ 2014-04-25 23:09 ` alex 2014-04-26 7:52 ` luc.linux 2014-04-26 12:26 ` Zé 1 sibling, 1 reply; 10+ messages in thread From: alex @ 2014-04-25 23:09 UTC (permalink / raw) To: Junio C Hamano; +Cc: Andrew Ardill, Jonathan Nieder, git > 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: gitignore vs. exclude vs assume-unchanged? 2014-04-25 23:09 ` alex @ 2014-04-26 7:52 ` luc.linux 0 siblings, 0 replies; 10+ messages in thread From: luc.linux @ 2014-04-26 7:52 UTC (permalink / raw) To: alex, Git Mailing List [-- 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 --] ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: gitignore vs. exclude vs assume-unchanged? 2014-04-22 17:54 ` Junio C Hamano 2014-04-25 23:09 ` alex @ 2014-04-26 12:26 ` Zé 1 sibling, 0 replies; 10+ messages in thread From: Zé @ 2014-04-26 12:26 UTC (permalink / raw) Cc: git@vger.kernel.org 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é ^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~2014-04-26 12:26 UTC | newest] Thread overview: 10+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2014-04-16 16:33 gitignore vs. exclude vs assume-unchanged? alex 2014-04-16 17:51 ` Junio C Hamano 2014-04-16 23:07 ` alex 2014-04-16 23:45 ` Jonathan Nieder 2014-04-18 0:36 ` alex 2014-04-22 0:40 ` Andrew Ardill 2014-04-22 17:54 ` Junio C Hamano 2014-04-25 23:09 ` alex 2014-04-26 7:52 ` luc.linux 2014-04-26 12:26 ` Zé
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).