Introduction

A .gitignore rule set that ignores everything except one file extension is possible, but it only works if you also unignore the directories Git must walk through. The main subtlety is that ignore rules are matched in order, and Git cannot include a file inside a directory that is still ignored. That is why this pattern usually needs both a broad ignore rule and one or more unignore rules.

Start with Ignore-All, Then Re-Include

A common pattern is to ignore everything, re-include directories, and then re-include the desired extension.

*
!*/
!*.md

This tells Git to ignore all paths, then allow directory traversal, then keep Markdown files. Without !*/, Git would not descend into ignored directories to find the allowed files.

Handle Nested Paths Explicitly When Needed

If the extension should be included anywhere in the tree, the directory unignore rule is the key part. If you want to limit inclusion to a specific subtree, make that explicit.

1*
2!docs/
3!docs/**/
4!docs/**/*.md

This version ignores everything except Markdown files under docs. It is often clearer than writing one global exception and then trying to re-ignore specific areas later.

Folder Structure Alone Is Not a Tracked Artifact

Git does not track empty directories by themselves. It tracks files. So if by "keep the folder structure" you mean keep empty directories even when no allowed file exists inside them, .gitignore alone cannot do that.

The usual workaround is a placeholder file such as .gitkeep.

1*
2!*/
3!.gitkeep
4!*.md

Then place a .gitkeep file in any otherwise-empty directory you want Git to preserve.

This point matters because many developers expect .gitignore to be able to preserve a pure directory tree by itself. It cannot. Git needs at least one tracked file in a directory before that directory becomes part of the repository state.

Order Matters in .gitignore

Ignore rules are processed from top to bottom, and later rules can override earlier ones. That means a correct set of patterns can still fail if the order is wrong.

A useful way to read the file is as a chain of increasingly specific exceptions. First block the world, then reopen the directories you need, then reopen the files you actually want tracked.

That mental model makes complicated ignore files much easier to debug.

It also keeps maintenance sane. When a new exception appears later, you can usually add it near the bottom without undoing the logic of the broader patterns above it.

Check What Git Thinks the Rule Means

When a path is unexpectedly ignored, use Git's own explanation tool.

git check-ignore -v docs/guide/intro.md

This shows which pattern matched the path. It is the fastest way to debug a .gitignore file that looks right but behaves differently than expected.

If a file is already tracked, remember that changing .gitignore will not automatically remove it from the index. Ignore rules affect new untracked files, not files Git is already managing.

Common Pitfalls

• Ignoring everything and forgetting to unignore directories with !*/.
• Expecting Git to track empty directories without a placeholder file.
• Writing patterns in the wrong order and accidentally overriding the desired exception.
• Using a global extension exception when only one subtree should be included.
• Debugging .gitignore behavior by guesswork instead of using git check-ignore -v.

Summary

• Ignore-all patterns work only if you also unignore the directory structure Git must traverse.
• Use *, then !*/, then the specific extension or subtree exceptions you want.
• Git does not track empty directories, so use placeholder files when needed.
• Keep .gitignore rules ordered from broad ignores to narrow exceptions.
• Use git check-ignore -v to see exactly why a path is ignored.