Clarify and expand descriptions of NonFiles#1734
Conversation
Discussed in: GitoxideLabs#1730 (comment) At least for now, they remain called `NonFile`s (and sometimes referred to as "non-files" in text), but more specifically defined.
Byron
left a comment
There was a problem hiding this comment.
Thanks so much for submitting this change, just in time and I think it's substantial!
Even though this PR goes for a minimal change to improve the documentation, the description also offered different variant names. Here I went for Untrackable which should help making clear what not to do when encountering such a directory entry.
There was a problem hiding this comment.
Going along with changing NonFile to Untrackable, I think the term "non-file" in documentation comments should also be reworded, since without NonFile, it's not clear what "non-file" means.
Since I don't know what other changes you plan, I don't know if the suggestions I've made here are the way to go or not.
Edit: It looks like you've enabled auto-merge so I'm guessing these changes won't conflict with any further changes you already plan to make here. I'll see if I can get these in as another commit (via the suggestion batching feature), which I think will cancel auto-merge and let you review them, but if it doesn't work out then I can open another PR.
This goes along with changing `NonFile` to `Untrackable`.
Head branch was pushed to by a user without write access
|
A great catch, thanks! I was a bit |
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
|
I just realized the commit message in 154b21f somewhat overinflates its importance: it's not changing documentation comments, but instead a regular comment and debug and assertion messages. (Fortunately, since it's not really changing documentation, it's not a conventional commit with |
This is a minor documentation revision, to make clearer what a
NonFile/"non-file" is, as discussed in #1730 (comment). At least for now, they are named the same, but the term is more specifically defined.A couple of possible other names that it could be changed to:
Otheras suggested in #1730 (comment). As noted, this is natural. But it is not specific. If Git uses this as a technical term, as suggested, then it should probably be used. I was unable to find it in a cursory search ofgit/giton GitHub, though. I didn't find anything for "NonFile" and everything I found for "non-file" was in phrases like "non-file mailmap," "non-file remote," "non-file backend," and "non-file argument."NonTrackable, or variations such asUntrackableandNotTrackable- This idea is from a commit message in a test that refers to the condition of not being aNonFileas that of being a "trackable file." I think this is also intuitive when considered abstractly, and accurate. But I'm not sure if it would be intuitive in practice.Instead of changing it to one of those here, I've just clarified and expanded the documentation. This is with the idea that, with the documentation adjusted this way, it should be possible to figure out if any other name still confers a significant improvement in clarity.
There is another conceptually related change that I made to nearby documentation that is not really covered by this. I'll post a review comment on it so that if it is considered out of scope or unwanted then it can be undone.,