How to git manage directories

Question

I know that git will not see an empty directory, but can anyone provide a link to some documentation on exactly how this is implemented. These are not only empty folders. If I add the file to a new folder, but I do not add it to the staging area, git will actually see the folder, but not the file.

Answer 1

I know that Git will not see an empty directory ...

This is not entirely correct. Git will see it just fine, it just won’t save it.

but can anyone provide a link to some documentation on how it is implemented.

Good software usually tries to hide implementation details, which suggests that Git is not very good :-), but in this case the implementation details are really pretty well hidden. Git internal documentation here , with one skeleton api-in-core-index.txt updated 9 years ago (!) And later index-format.txt . In any case, tracking is a Git index that has several names: “index”, “staging area” and “cache”.

These are not only empty folders. If I add the file to a new folder, but I do not add it to the staging area, Git will actually see the folder, but not the file.

This is also not entirely correct. Try running git status -uall (or, equivalently, git status --untracked-files=all ). ¹ What happens is that the git status command usually sums up the raw files with a simple rule: if a directory named dir exists and some unplayable files were found inside dir , but no tracked files were found in dir , Git simply prints dir/ , rather than listing each file in dir .

If you use -uno (or --untracked-files=no ), Git doesn't even look for unnecessary files, which saves time. In a large repository (tens of thousands of directories, hundreds of thousands or even millions of files), this can make the difference between git status occupied in less than one second, and git status will take many seconds.

Finding all raw files requires comparing the actual working tree with the cached version of the work tree stored in the index. In normal (summary) mode, Git can sometimes use its cache to avoid not only listing files in dir , but even browsing inside dir , which also saves time.

Of course, without looking for an unnecessary file on all means, Git will never remind you to git add such files. Thus, the default mode (summation) is understood as a compromise, both in terms of speed ("If dir contains any ² files by itself or through subdirectories, but we no longer know the files inside dir tracked, do not interfere with fine-grained file checks ") and usability (" there is no need to spam the list with 19,365 file names in dir , when we can just say dir/ ").

---

¹ By default, if you do not specify options, this is -unormal , but if you specify -u , it means -uall . However, you can set the status.showUntrackedFiles configuration variable to change the default value.

² Testing this ("does dir or its subdirectories contain any regular files") depends in part on the support for the d_type field in readdir 's dirent data that is not required by POSIX but is common (it is certainly found in all modern Unix versions). In recent versions of Git, there is also a “no trace” extension in the index format described in the same technical documentation , which allows Git to skip reading unsigned directories if their stat data has not changed using the mtime field of the mtime structure .

Answer 2

There are two levels: what happens under the hood (plumbing) and what you actually see (porcelain).

To find out all about the plumbing layer, I recommend checking it out may cause problems later . If you want to achieve a similar effect, you can put the file in a directory. If you want the directory to remain empty, you can use this solution ; if you don't care if people add files later, it could be a README or an empty .gitignore .