The previous lesson left task-manager with a history that is readable, bisectable and reversible. But an impeccable history can contain rubbish, and task-manager's does contain it: Bruno pushed the entire node_modules folder without noticing — 14,000 files and 180 MB —, Carla has been scattering Thumbs.db files across the image directories, Bruno's macOS leaves a .DS_Store in every folder he opens in Finder, and in some commit from months ago there is a config.js file with the test database password in it.

This lesson is about the first line of defence against all of that: .gitignore, the mechanism by which you tell Git which files it should not even consider versioning. We mentioned it in passing in lesson 02-04, when looking at git status, and we promised to develop it here.

It is a deceptively simple file. Its syntax has corners that confuse everybody — negation, the leading slash, the directory trap — and, above all, it hides a rule that is the cause of 90 % of the Git questions on forums: .gitignore is no use for stopping the tracking of a file that is already versioned.

1. Why what is not versioned matters
2. What must never go in: a table by category
3. How it works: precedence and scope
4. Complete syntax of the patterns
5. Negation with ! and its trap
6. The three levels: project, local and global
7. The rule that confuses everybody: it only affects untracked files
8. Untracking with git rm --cached
9. Debugging with git check-ignore -v
10. Forcing with git add -f
11. Templates by language
12. The pattern for secrets: .env and .env.example

Versioning what should not be versioned has four costs, and all four are bigger than they look:

There is one principle that orders every decision:

You version the source, not the result. If a file can be regenerated from other files in the repository, it is not versioned. If it contains information belonging to one machine or one person, it is not versioned. If it is a secret, it is never versioned.

With two important exceptions that are worth knowing, because they are the ones that confuse:

• Dependency lockfiles (package-lock.json, yarn.lock, Cargo.lock in applications) are versioned. They are not a result: they are the source of reproducibility. Without them, two people install different versions.
• Shared project configuration (.editorconfig, .gitattributes, the part of .vscode/ that defines tasks and recommended extensions) is versioned. It is source, not result.

The .gitignore the task-manager team ended up adopting:

Notice the two uses of ! (negation) at the end of blocks: !.env.example and !.vscode/extensions.json. We explain them in section 5, along with the trap they hide.

Three rules govern the behaviour:

Rule 1: .gitignore applies per directory and downwards. A .gitignore affects its own directory and all of its subdirectories. You can have several in the same repository.

Rule 2: the most specific pattern wins. Git evaluates, in this order of increasing priority:

1. core.excludesFile (the user's global)
2. .git/info/exclude (local to the repository)
3. The .gitignore files of the directories, from the root downwards (the deepest one wins)
4. The command line (git add -f)

Rule 3: within a single file, the last matching line wins. That is why negations go after the pattern they cancel:

The .gitignore is versioned. It is part of the project and it must be in the first commit. If it is not, every person on the team has to work out for themselves what they must not push, and somebody will get it wrong.

Git uses a syntax derived from shell globs, with a few peculiarities of its own.

The leading slash anchors to the root. It is the most important difference and the most forgotten:

If your project has build/ in the root and also src/components/build/ which you do want to version, you need the leading slash.

A slash in the middle of the pattern also anchors. This is the rule that takes people by surprise: if the pattern contains a / in any position other than the final one, it is interpreted as relative to the .gitignore's directory, not as "at any depth".

Git does not version directories, only files: an empty directory simply does not exist as far as Git is concerned. If your application needs data/ to exist on start-up, the usual pattern is:

And you create an empty data/.gitkeep file. There is nothing special about the name — Git does not know it — it is only a convention for saying "this file exists so that the directory exists".

Notice that we use data/* and not data/. The reason is the trap in the next section.

The rule that wastes the most time in any .gitignore:

If a directory is ignored, Git does not go into it. Therefore, you cannot un-ignore a file that is inside an ignored directory.

It is a deliberate optimisation: Git does not walk thousands of files in node_modules/ just in case some later rule rescues one of them. And it produces this failure, which looks like a bug in Git and is not:

data/important.csv is still ignored. Git has discarded the whole of data/ and has never got as far as evaluating the second line.

The correct way is to ignore the contents, not the directory:

With data/*, Git does go into data/, ignores each of its children individually, and the negation can rescue one of them.

If the file you want to rescue is deeper down, you have to un-ignore every intermediate level:

Translated: ignore everything (*), but do not ignore the directories (!*/, necessary so that Git can go into them), and explicitly rescue that file.

This whitelist pattern — "ignore everything and rescue what I want" — is aggressive but very useful in repositories where what is versionable is a minority (for example, a configuration repository):

Let us go back to the two negations we left pending:

It works because .env.* ignores files, not a directory, and the later negation rescues one. Correct.

Notice .vscode/* and not .vscode/. If we had written .vscode/, the two negations would do nothing. This is exactly the mistake everybody makes the first time.

There are three places to declare exclusions, and choosing the wrong one is the cause of a recurring argument in the team: Carla proposed adding .idea/ to the project's .gitignore and Ana objected because nobody else uses that IDE. They were both partly right, and the problem was one of level.

Would this file appear on the machine of anybody working on this project? If so, it goes in the project's .gitignore. If it appears only because of your operating system or your editor, it goes in your global. If it is a whim of yours in this particular repository, it goes in .git/info/exclude.

Strictly speaking, .DS_Store and .idea/ go in the global. In practice, almost every project also puts them in the project's .gitignore, as a safety net for anybody who does not have the global configured. It is defensive and it is reasonable; you just have to know that it is a deliberate duplication.

On macOS and Linux, Git already uses ~/.config/git/ignore without you having to configure anything if the file exists. It is the default location according to the XDG standard:

It is a normal .gitignore that lives inside .git/. Like everything in there (lesson 01-04), it is neither versioned nor cloned:

The advantage over modifying the project's .gitignore: you do not clutter the shared file with your quirks, and you do not have to justify them in a review. The disadvantage: it is lost if you delete the repository and clone it again.

Here is the source of 90 % of the questions about .gitignore:

.gitignore only affects UNTRACKED files. If a file is already in the index, Git will carry on recording its changes no matter how many patterns you write.

Remember the three states from lesson 01-03 and the cycle from lesson 02-03. .gitignore acts exclusively on the transition from untracked to staged: it tells Git "do not even offer it to me in git status, and do not pick it up with git add .". On a file that has already crossed that boundary, it has no effect at all.

The typical scenario, which happened to Bruno:

It is still there. The .gitignore has done nothing, because those files are already tracked.

The return arrow — git rm --cached — is the only way of taking a file back to the state where .gitignore can protect it.

git rm --cached removes the file from the index but leaves it on your disk. From that moment it becomes untracked, the .gitignore starts to apply and it disappears from git status.

The complete flow, just as Ana did it:

When there are many files that ought now to be ignored, there is a recipe that takes them all out at once, respecting the current .gitignore:

git rm -r --cached . deletes nothing from disk: it empties the index. git add . fills it again, and this time it does respect the .gitignore. The difference between the two states is exactly the set of files that should not have been there.

Always check with git status before committing. If the .gitignore has an overly broad pattern, this recipe can untrack files you actually wanted.

Warning 1: the file is deleted on everybody else's machine. As far as Git is concerned, a git rm --cached followed by a commit is a deletion. When Bruno and Carla pull, that file will disappear from their working copy. With node_modules/ it does not matter (it is regenerated with npm ci), but if you untrack a config.js that people need, you are deleting it for them. Tell the team before you do it.

Warning 2: it deletes nothing from the history. And this one is critical:

The file disappears from the tip, but it is still in every previous commit:

If config.js contained a password, the password is still in the repository and in every clone. git rm is not a security tool. The correct procedure for a secret that has already leaked — rotate the credential first, then rewrite the history — is the content of lesson 08-05.

The day comes when a file is ignored and you do not know why, or the other way round. git check-ignore -v answers: it tells you which exclude file, which line and which pattern are making the decision.

It reads: the dist/ pattern, on line 8 of the .gitignore file, is the one that ignores dist/app.min.js.

Examples of the three possible answers:

git status --ignored deserves a section of its own, because it is the way to discover surprises:

Every !! is a file or directory that Git is hiding. If you see something there that you did want to version, you now know that a pattern is too broad.

If a file is tracked, check-ignore can be confusing, because the patterns do match even though they have no effect. To ask "would any pattern match, regardless of whether it is tracked?":

That is: there is a pattern that would cover it, but since the file is already in the index, it has no effect. That diagnosis — "the pattern is fine, the problem is section 7" — is exactly what you need to know.

Sometimes you need to version a file that a broad pattern is ignoring. git add -f (or --force) skips the rules for that particular operation:

Without -f, Git warns you and does nothing:

Beware of what happens next. Once added with -f, the file becomes tracked, and by the rule in section 7 the .gitignore stops having any effect on it for ever: every modification will show up in git status. -f is not a one-off exception, it is a permanent change of state.

That is why it is almost always better to fix the pattern than to force:

That way the exception is documented in the repository instead of living in the memory of whoever typed -f one day.

And a warning that links to the next lesson: -f is the route by which secrets slip in. Somebody is in a hurry, Git complains that .env is ignored, and git add -f .env solves the problem of the next five minutes in exchange for creating a permanent one. If Git resists adding a file, stop and think about why.

There is no need to write a .gitignore from scratch. There are community-maintained collections with templates by language, framework, operating system and editor; the best known is the github/gitignore repository, and most platforms offer you the choice of one when you create the repository.

Recommendations for using them:

1. Start from your language's template, but read it. It contains rules for tools you may not use, and sometimes it ignores things you do want.
2. Combine, do not blindly concatenate. A Node template plus a Python one plus three editor ones produces a 300-line file that nobody maintains.
3. Group into sections with comments, as in the example in section 2. A .gitignore gets read many times.
4. Operating system and editor rules belong in your global. If the whole team has their global properly configured, the project's .gitignore stays short and meaningful.
5. Review it when the tooling changes. A .gitignore with rules for a bundler you stopped using two years ago is noise.

A useful check from time to time, to see which rules are no longer of any use:

If a rule never shows up here on any machine in the team, it is probably superfluous.

The real problem: the application needs to know the database URL, the mail API key and a session secret. Those values cannot be in the repository, but whoever clones the project has to know which values are needed and what they are called.

The conventional solution is two files:

.env — with the real values. Ignored, never versioned.

.env.example — with the keys and sample values, nothing real in it. Versioned.

And in the .gitignore, with the negation we already know:

Why it works well:

• Diego clones his fork, copies .env.example to .env, fills in his values and starts up. The documentation of what is needed is in the repository, up to date, because it is part of the code.
• When somebody adds a new variable, the PR review notices that it is missing from .env.example. It is a good candidate for an automatic check in CI.
• The sample values are obviously fake (put-your-key-here), so nobody mistakes them for real ones or tries to use them.

The three mistakes that ruin the pattern:

1. Putting real values in .env.example "to make it more convenient". Then the versioned file is the one with the secret in it, and you have gained nothing.
2. Writing .env* without the negation. The .env.example gets ignored too, nobody pushes it, and the whole pattern ceases to exist.
3. Adding the .gitignore too late. If .env has already been committed at some point, git rm --cached takes it off the tip but not out of the history (section 8). The secret is still there.

That third case — the secret that has already leaked — has a procedure of its own, with an order of steps that matters a great deal: first you rotate the credential, then you rewrite the history. It is the heart of lesson 08-05.

Mistake 1: believing that .gitignore untracks an already versioned file. It is misunderstanding number one. It only acts on untracked files; for everything else, git rm --cached.

Mistake 2: data/ when you meant data/*. If the directory is ignored, Git does not go into it and no later negation works. Ignore the contents, not the directory.

Mistake 3: putting the negation before the pattern. The last matching line wins. !errors.log followed by *.log is useless.

Mistake 4: forgetting the leading slash. build/ ignores any build in the project; /build/ only the one in the root. It usually matters more than it seems.

Mistake 5: using git add -f as your usual solution. It makes the file tracked for ever and leaves the exception undocumented. Fix the pattern and write the negation.

Mistake 6: .env* without !.env.example. It breaks the whole secrets pattern.

Mistake 7: trusting git rm --cached to remove a secret. It only takes it off the tip. The history and every clone still hold it. Lesson 08-05.

Mistake 8: filling the project's .gitignore with personal rules. .idea/ and *.swp belong to your machine; they go in core.excludesFile. The project's .gitignore should contain only what would happen to anybody.

Tip 1: create the .gitignore in the first commit. Before installing dependencies. It is infinitely cheaper than cleaning up afterwards.

Tip 2: git status --ignored from time to time. It is the only way of seeing what Git is hiding, and of spotting overly broad patterns.

Tip 3: git check-ignore -v the moment you are in doubt. It answers in a second what otherwise turns into half an hour of trial and error.

Tip 4: configure your core.excludesFile once in your life. It saves you dirtying every repository you ever work in.

Tip 5: comment the .gitignore by sections. And explain the odd patterns. A year from now nobody will remember why !config/production/settings.json is there.

Tip 6: validate .env.example in CI. A check comparing the keys in .env.example with the ones the code reads from process.env stops them drifting apart.

In a test repository, create this structure:

1. Write a .gitignore with data/ and !data/public.csv. Check with git status and with git check-ignore -v that public.csv is still ignored, and explain why.
2. Fix it so that public.csv is versioned and everything else stays ignored.
3. Now get data/backups/private-2026.csv versioned as well, without versioning private.csv.
4. Verify each step with git check-ignore -v.

Simulate Bruno's disaster:

1. Create a repository, an app.js, a node_modules/ directory with three files, a .env with a fictitious password and a .DS_Store.
2. Commit it all without a .gitignore (the initial mistake).
3. Now add a correct .gitignore, with the secrets pattern from section 12.
4. Check that git status still shows the files that should be ignored and explain why.
5. Untrack them with the recipe from section 8, without deleting them from disk.
6. Verify that git status comes out clean, that the files are still on your disk and that git status --ignored shows them as ignored.
7. Show that the password in the .env is still accessible in the history and say which lesson solves that.

1. Configure a global core.excludesFile with the rules for your operating system and your editor.
2. In a test repository, add a personal-notes.md file to .git/info/exclude.
3. Add the rule dist/ to the project's .gitignore.
4. Create the three types of file and check with git check-ignore -v that each one is ignored by the correct level.
5. For each of these files, decide with reasons which level the rule should be at: node_modules/, .idea/workspace.xml, carla-tests.js, coverage/, .DS_Store, .env.

Solution 1:

data/public.csv does not show up: it is still ignored.

The diagnosis is explicit: the decision is made by line 1, with the data/ pattern. The negation on line 2 is never evaluated, because Git, having ignored the data/ directory, does not go into it. It is a deliberate performance optimisation.

The key to step 3: you have to un-ignore the intermediate directory (!data/backups/) so that Git goes into it, and then ignore its contents again (data/backups/*) so that you can rescue only what you want. Every level of depth demands its own pair of lines.

Solution 2:

It still shows up because it is already tracked. .gitignore only acts on the "untracked → staged" boundary, and these files crossed it in step 2.

The D entries are exactly the files that should not have been there. app.js does not appear because its content has not changed.

There it is. Anybody with access to the repository, now or five years from now, can recover it with a single command, and every existing clone contains it. git rm --cached protects the future, it does not repair the past. The correct procedure — rotate the credential first and then rewrite the history with git filter-repo — is the content of lesson 08-05.

Solution 3:

app.js does not appear: it is not ignored by any rule. Each of the other three is ignored by exactly the level it belongs to.

5. Where each rule goes:

The last row is the underlying criterion: the greater the consequence of the rule being missing, the higher up it should be and the more versioned it should be.

The essentials of this lesson:

• You version the source, not the result. Out go dependencies, build artefacts, operating system files, personal editor configuration, logs, temporary files, large binaries and — above all — secrets. In stay the dependency lockfiles and the shared project configuration.
• The syntax has three rules you have to take on board: the trailing slash means "directories only", the leading slash anchors to the root, and any slash in the middle of the pattern also anchors. Within a file, the last matching line wins.
• Negation with ! has a hard limit: you cannot un-ignore a file inside an ignored directory, because Git does not even go in. You ignore the contents (data/*), not the directory (data/).
• There are three levels: the project's .gitignore (versioned, for what happens to anybody), .git/info/exclude (local, for your things in that repository) and core.excludesFile (global, for what your operating system or your editor generates). The more serious the consequence of a rule being missing, the higher up and the more versioned it should be.
• The rule that confuses everybody: .gitignore only affects untracked files. On what is already versioned it has no effect. The way back is git rm --cached, which removes from the index but keeps on disk, with two warnings: it deletes the file on everybody else's machine when they pull, and it does not touch the history.
• git check-ignore -v answers in a second which file, which line and which pattern are deciding. git status --ignored shows what Git is hiding from you.
• git add -f forces the issue, but it makes the file tracked for ever. It is nearly always better to write the exception as a negation, so that it is documented.
• The pattern for secrets is an ignored .env plus a versioned .env.example with keys and obviously fake values, plus the !.env.example negation. It is the best possible documentation of what configuration the project needs.

task-manager now knows which files must not go in. The other side of the problem remains: the files that do go in, but that Git should not treat as though they were all the same. A PNG is not a text file and there is no sense in trying to merge it. A CHANGELOG.md would like to be merged in a special way. And, above all, there is the problem Carla has been dragging along since module 1: every time she edits a file on Windows, git diff marks every line as modified.

That is the territory of lesson 08-04: File Attributes with .gitattributes.