Feedback request: catching documentation files missing from a fresh Git clone

[ultimateswagger]

🏷️ Discussion Type

Question

Body

Hi everyone,

I’m working on a small documentation checker called Markdown Local Check and would appreciate some feedback on a new feature.

The problem is simple: a README links to a screenshot or guide that exists on your computer, so the link looks fine. But the file is ignored or was never committed, and someone cloning the repository does not receive it.

The new --fresh-clone option checks local documentation links against the latest Git commit. It reports ignored files, files that have not been committed, staged files, empty directories, and links outside the repository. Each report includes the Markdown filename and line number.

For example:

README.md:12: target exists locally but is ignored by Git: screenshots/setup.png

Repository and instructions: https://github.com/Anubis371/markdown-local-check
Git checks: https://github.com/Anubis371/markdown-local-check/blob/main/src/git.js
Regression tests: https://github.com/Anubis371/markdown-local-check/blob/main/test/fresh-clone.test.js

It runs offline with Node.js and Git, without extra packages. There are 16 tests. It checks documentation file availability, not whether the application starts, and it does not verify that your local commit was pushed. Submodules and symbolic links need separate checks.

I’d particularly appreciate feedback on:

1. Are there Git or filesystem edge cases the current tests should cover?
2. Are the messages clear about why a file will be missing from a clone?
3. Would you prefer this as a manual check or part of your GitHub Actions workflow?

If you have time to try it, a small failing example or one concrete suggestion would help. Thanks for taking a look.

Guidelines

• I have read and understood this category’s guidelines before making this post.

[baidikgithub]

Useful feature. I read src/git.js, and here are a few concrete points:

Edge cases to test

• Case mismatch: on macOS/Windows, Screenshots/Setup.png resolves locally even when the commit has screenshots/setup.png, but it breaks on GitHub and Linux. Right now this gets reported as "not in the latest commit". A dedicated "case differs" message would be clearer.
• Files inside a submodule or symlinked folder: the 160000/120000 checks only match the exact path. A link like vendor/lib/README.md gets misreported. Checking parent folders would fix this.
• Root-relative links (/docs/img.png) and encoded links (my%20file.png, guide.md#install).

Messages
git check-ignore -v returns the matching rule, so you could show exactly why a file is excluded:
README.md:12: screenshots/setup.png is ignored by .gitignore:4 (*.png)

Manual vs. Actions
In Actions, the checkout already is a fresh clone, so the normal link check catches these files there. --fresh-clone is most useful as a pre-push hook on the developer's machine. A short README example for that setup would help people adopt it.

[Icaro0310]

Solid idea — the gap between "exists locally" and "exists in the commit" is exactly where doc links rot. On (1), the edge cases I would add to the test matrix:

• Case mismatches — screenshots/Setup.png committed but linked as setup.png. Passes on macOS/Windows (case-insensitive FS), breaks on a Linux clone. This is probably the single most common real-world cause of broken doc images.
• Non-.gitignore ignore rules — files ignored via .git/info/exclude or a global core.excludesFile. If you only read .gitignore you will miss them; git check-ignore -v <path> covers all three sources.
• Index bits — files marked --assume-unchanged or --skip-worktree. They look present and committed, but a fresh clone sees different content.
• Percent-encoding and fragments — My Doc.md vs My%20Doc.md vs ./My Doc.md#section, plus Windows-style ..\\images\\x.png separators.
• git-attributes filters — export-ignore marks the file as committed but excluded from git archive exports (relevant if consumers get the repo via tarball, not clone).
• Renames staged but uncommitted — git mv in the index; the old path is gone in HEAD, the new one is not yet in HEAD.

The staged-file report you already have is genuinely rare in these checkers — most only compare worktree vs HEAD, not worktree vs index vs HEAD.

—
Check my work: github.com/Icaro0310 · icaro0310.github.io

[halith-smh]

Hey, really like this idea. Broken README images are such a common problem. I went through git.js and found a few cases you might want to add:

Git LFS: if an image is tracked with LFS, your check passes because it's committed normally. But anyone who clones without LFS just gets a tiny pointer file, and the image breaks. Even actions/checkout has LFS off by default. You can catch these with git check-attr filter -- <path>, which returns lfs for those files.

Links with ?raw=true: a lot of READMEs link images like setup.png?raw=true. Might be worth a quick test to make sure the query part gets stripped before you check the path.

Files removed with git rm --cached: the file is still in HEAD, so it passes, but the next commit will delete it. Since you already load the staged files, you could warn something like file will be removed by the next commit.

One small suggestion for the messages: it'd help to tell people how to fix it, like:

not in the latest commit (run: git add <file> && git commit)

Nice work on the tests too. They're easy to follow. Happy to help write a test for any of these if you want.

[mayo-byte07]

Hey, this is a brilliant tool! I completely agree with the others that --fresh-clone is best suited as a local pre-push or pre-commit hook rather than a GitHub Action. In CI, a fresh checkout already exposes missing files naturally, so running this locally saves developers that frustrating round-trip delay.

Regarding edge cases, definitely prioritize case mismatches between macOS/Windows and Linux, and stripping URL parameters or fragments (like img.png?raw=true or file.md#setup). I'd also suggest handling relative path resolutions carefully, especially when the markdown file is deeply nested and referencing assets in a parent directory.

For the output messages, extracting and appending the exact .gitignore rule or a quick fix command would be fantastic. Great work building this out!