How repositories are found
Six rules in total, and the result is identical on macOS, Linux and Windows.
The six rules
- The search starts at the current directory and goes down one level by default;
--depthreaches further. - A directory counts as a repository when it holds a
.gitdirectory or a.gitfile, which is what makesgit worktreeand submodule checkouts work. - Once a repository is found, mgit does not descend into it, so a submodule or a vendored project is never counted twice.
- Symbolic links are followed and reported under the name you can see: with
repoandlink -> reposide by side, both names are run. Each real directory is only entered once, so a link loop cannot spin forever. - Results are sorted by name, case insensitively, with the exact spelling breaking ties, so the order is the same on all three operating systems.
- When nothing is found, mgit warns and exits with
1. But if the current directory itself is a repository, mgit runs git right there and behaves exactly like plain git.
Try it on a directory with a second level: mgit --list
What --depth means
Levels are counted down from the current directory: --depth 1, the default, sees direct subdirectories, and --depth 2 sees one more level. Because of rule 3, a larger depth never makes mgit walk into a repository it has already found.
Compare depth 1 and 2: mgit --depth 2 --list
mgit --list tells you exactly which directories are involved.Worktrees and submodules
A directory created by git worktree, and the working directory of a submodule, keep their .git as a file rather than a directory. mgit accepts both, so both kinds of directory are found and run.
See a .git that is a file: mgit --list
Symbolic links
A link is reported under the name you see, deliberately matching the */ glob behaviour of the 1.0 shell version. Each real directory is entered only once, so even a directory linked back to its own parent finishes the walk.
See what a link does: mgit --depth 2 --list
A directory that cannot be read
A directory without read permission does not fail the run: mgit writes one warning to stderr and finishes the rest of the walk.
See the warning, and the rest still running: mgit --depth 2 --summary
Nothing found
When no repository is found, mgit prints a warning on stderr and exits with 1. This is one of the defects 2.0 fixed on purpose: 1.0 was completely silent and returned 0. --allow-empty brings the old exit code back.