How .gitignore Works, and How to Build One

After reading this you will know exactly how Git decides which files to ignore, how to read a pattern line by line, and how to assemble a correct .gitignore from language and editor templates without breaking files you already committed.

What a .gitignore actually does

A .gitignore file is a list of patterns. Git checks every untracked file against those patterns and hides the matches from status output and from git add. That is the whole job. It does not delete files, and it does not touch anything Git is already tracking.

Here is the hook. Suppose your project has a node_modules folder with 41,382 files. Without a rule, git status lists all of them. Add one line:

Now those 41,382 files vanish from status in one step. The trailing slash means "match a directory named node_modules and everything inside it". Git stops descending into that folder entirely, which is also why a single directory rule is faster than 41,382 individual file rules.

When to use a generated template, and when not

Reach for a generated .gitignore at the start of a project, or when you add a new language or tool to an existing one. The templates cover the files that a Python interpreter, a Node install, a JetBrains IDE, or macOS drops into your working tree without asking: __pycache__/, node_modules/, .idea/, .DS_Store. These are predictable across every project, so a curated list beats writing them from memory.

Do not use a template as a place to hide secrets. A .env file with database passwords should be ignored, yes, but ignoring it is not the same as securing it. If that file was ever committed, the password is in your history forever until you rewrite it. The ignore rule only stops future accidental commits.

Also skip the template for files that are specific to one machine or one developer. Those belong in .git/info/exclude or your global ignore file, not in the shared repository file, because your teammates do not have your editor or your local scratch files.

How Git matches a pattern

The rules come from the gitignore specification, and they are more precise than most people assume. Six facts govern every match.

Blank lines and comments

A blank line matches nothing and is used for spacing. A line beginning with # is a comment. To match a literal file named #test, escape it as \#test.

Trailing slash

A pattern ending in / matches directories only. build/ matches a directory but not a file called build.

Leading slash

A slash at the start anchors the pattern to the .gitignore file's own directory. /config.json matches only at the top level, not src/config.json.

Middle slash

Any slash that is not at the end also anchors the pattern relative to the file. doc/frotz matches doc/frotz but not a/doc/frotz.

No slash

A pattern with no slash (except a trailing one) matches at any depth. *.log matches app.log and logs/server/app.log alike.

Negation

A line starting with ! re-includes a file the previous rules excluded. Order matters, and you cannot re-include a file if its parent directory is already ignored.

The wildcards themselves follow shell globbing. A single * matches any run of characters except /. A ? matches exactly one character except /. A double ** is special: **/foo matches foo at any depth, foo/** matches everything under foo, and a/**/b matches a/b, a/x/b, a/x/y/b and so on.

The precedence rule, stated exactly

When more than one pattern could apply, the last matching pattern wins. Read the file top to bottom; the final line that matches a given path decides its fate.

Here f is a file path, and p_1, p_2, \ldots, p_n are the pattern lines in file order. Whichever p_i with the largest index i matches f sets the outcome: ignore if it is a normal pattern, keep if it starts with !. If no pattern matches, the file is not ignored.

This is why a generator labels and orders its blocks carefully. If a Python block ignores *.log and a later custom block re-includes !important.log, the order of those two lines is the entire difference between committing that file and losing it.

Merging templates without duplication

Combine three or four templates by hand and you will produce the same line several times. Node and a generic editor template both ignore *.log. macOS and Windows both list clutter files. The generator merges identical lines so each pattern appears once, and it labels each block with a comment header so you can see where a rule came from.

Deduplication matters for readability, not correctness: Git treats a pattern that appears twice exactly as it treats it once. But a 200-line file with 40 duplicate lines is hard to audit, and auditing is the point. You should be able to read your .gitignore and know why every file is hidden.

Common mistakes

The re-inclusion trap above is the most frequent, but four others cost real time.

Editing after committing. Adding secrets.txt to .gitignore does nothing if you already ran git add secrets.txt. Git keeps tracking it. Run git rm --cached secrets.txt to stop tracking while keeping the file on disk, then commit that change.

Anchoring by accident. A single slash anywhere except the end anchors the pattern to the file's directory. People write src/*.tmp expecting it to match .tmp files in every src folder; it only matches the top-level one. Use **/src/*.tmp or drop the path.

Trailing whitespace. A space at the end of a line is significant unless escaped or unless it is trailing space that Git strips. To match a filename that genuinely ends in a space, escape the final space with a backslash. Most such lines are typos.

Ignoring the whole config folder. Teams ignore .vscode/ wholesale, then lose shared launch settings. Ignore the machine-specific files inside it and commit the rest.

Related tools

A .gitignore often sits beside config files you also need to check. If your repository holds JSON config, the JSON Formatter & Validator confirms it parses before you commit. To move settings between formats, the data converter handles JSON, YAML, TOML, XML and CSV. When you want to see exactly what changed between two config versions, the JSON Diff gives a structural comparison.

The pattern matching in .gitignore uses glob syntax, not regular expressions, but if you are testing true regular expressions for a related task the Regex Tester explains each token in plain English. To escape a filename with special characters for a shell command like git rm, the String Escaper handles shell and JSON escaping.

Related tools

JSON Formatter & Validator

Format, validate, minify and query JSON with JSONPath.

JSON Schema Validator

Validate JSON data against a JSON Schema.

JSON ↔ YAML ↔ TOML ↔ XML ↔ CSV

Convert between the five common data formats.

Regex Tester

Test regular expressions live, with a plain-English explanation.

SQL Formatter

Pretty-print and minify SQL for any major dialect.

JSON Diff

Structural diff of two JSON documents.