Introduction

Adding a comment to a .gitignore file is simple: start the line with #. Git ignores that line as documentation instead of treating it as a file pattern.

Comments are worth using because .gitignore files tend to grow over time. A few short explanations make it much easier to see why certain files are excluded and which rules belong together.

Use # at the Start of the Line

A basic comment looks like this:

# Build output
bin/
obj/

Git reads the # Build output line as a comment and the following lines as actual ignore patterns.

This works equally well for:

• section headers
• short explanations
• reminders about team-specific decisions

For example:

1# Local environment variables
2.env
3
4# macOS Finder metadata
5.DS_Store

That is usually all you need.

Group Related Rules with Comments

The best .gitignore files are organized by purpose, not just by a random accumulation of patterns. Comments help create those sections.

1# Node dependencies
2node_modules/
3
4# Build artifacts
5dist/
6coverage/
7
8# IDE settings
9.idea/
10.vscode/

This makes the file easier to maintain because future edits have an obvious place to go. It also reduces the chance that someone deletes a rule without understanding why it existed.

Know How to Ignore a Literal #

A line that begins with # is a comment, so if you ever need to match a filename that actually starts with #, escape it with a backslash:

\#notes.txt

That tells Git the # is part of the pattern, not the start of a comment.

The same idea applies to other special pattern rules in .gitignore: syntax that looks like plain text may still have special meaning to Git.

Use Comments to Explain Exceptions

Comments are especially helpful when you use negation rules with !, because those rules can be hard to read later.

1# Ignore all log files
2*.log
3
4# Keep the sample log for debugging docs
5!sample.log

Without the explanation, the exception can look arbitrary. With the comment, the reason is clear.

That kind of tiny annotation pays off more than people expect, especially in long-lived repositories with many contributors.

It is also useful in template repositories, where a short comment can explain which ignores are project-specific and which ones are only there because of a particular toolchain or editor.

Common Pitfalls

The biggest mistake is assuming comments can appear at the end of a pattern line the way they do in some configuration formats. In .gitignore, # starts a comment when it begins the line. If you want documentation, put it on its own line.

Another common issue is forgetting that comments do not affect already tracked files. If a file is already in Git history, adding an ignore rule or a comment does not untrack it.

It is also easy to over-comment obvious patterns. Good comments explain intent, not what the syntax already says plainly.

Finally, if you need to match a filename that literally starts with #, remember to escape it or Git will treat it as a comment.

Summary

• Add a .gitignore comment by starting the line with #.
• Use comments to group related rules and explain unusual patterns.
• Put comments on their own lines rather than at the end of pattern lines.
• Escape # if it is part of a literal filename pattern.
• Use comments to document intent, especially for exceptions and team-specific rules.