What you can do after this lesson
You will be able to keep unwanted files out of a repository: secrets, logs, build output, editor settings and operating system clutter. You will also know what to do when something slipped in anyway. Throughout we use a small website folder.
Why some files should never be committed
A repository should hold the source that people need to rebuild and run the project. It should not hold:
- Secrets: passwords, API keys and
.envfiles. Once committed, they live in history. - Generated files: compiled output and downloaded packages that a build step recreates.
- Logs and temporary files: noise that changes constantly and creates meaningless diffs.
- Personal clutter: editor settings and files such as
.DS_Storecreated by your operating system.
Git will list all of these as untracked and keep reminding you about them in git status. A .gitignore file makes it stop.
Creating the rules
Create a text file named .gitignore in the project root. One pattern per line. Here is a practice setup, with output showing the effect:
mkdir logs build
echo x > logs/app.log
echo x > build/out.js
echo "SECRET=1" > .env
echo "<h1>Hi</h1>" > index.html
echo x > notes.tmp
git status -s?? .env
?? build/
?? index.html
?? logs/
?? notes.tmpNow add the rules:
.env
*.tmp
logs/
build/Save those four lines as .gitignore and run status again:
git status -s?? .gitignore
?? index.htmlThe ignored files disappeared from the list. Notice .gitignore itself is untracked: commit it, so teammates get the same rules.
Pattern rules in brief
*.tmpmatches any file ending in.tmpin any folder.*matches any characters except/.logs/with a trailing slash matches directories only./config.localwith a leading slash matches only at the top level of the repository.**/cachematches acachefolder at any depth.- Lines starting with
!re-include something a previous line excluded. - Lines starting with
#are comments. Put them on their own line in the file; blank lines are ignored.
The negation rule has a trap. You cannot re-include a file if a parent directory is ignored. In a test repository, these rules did not rescue keep.txt:
build/
!build/keep.txtGit still ignored it, because it skips the whole ignored directory. Ignore the directory's contents instead:
build/*
!build/keep.txtWith those two lines, git status -s -uall listed build/keep.txt as a new file while build/out.js stayed ignored.
Testing a rule
When a file is ignored and you cannot tell why, ask Git:
git check-ignore -v .env notes.tmp logs/app.log.gitignore:1:.env .env
.gitignore:2:*.tmp notes.tmp
.gitignore:3:logs/ logs/app.logEach line shows the file, the line number and the pattern that matched. To list everything currently ignored, use git status --ignored -s, where ignored files carry !!.
When a file is already tracked
Ignoring only affects untracked files. Suppose a log file was committed, and later you add *.log to .gitignore. Git keeps tracking it:
echo "*.log" >> .gitignore
echo more >> tracked.log
git status -s M .gitignore
M tracked.logTo stop tracking while keeping your local copy, remove it from the staging area only:
git rm --cached tracked.log
git status -s M .gitignore
D tracked.logCommit that, and from then on the file is both ignored and untracked. After committing, git ls-files lists .gitignore and index.html only, while git status --ignored -s shows tracked.log ignored with !!. For a whole folder use git rm -r --cached folder/.
Global ignores and forcing
Files that are specific to you, such as .DS_Store on macOS or editor folders, do not belong in a project's rules. Create a personal list and tell Git to use it everywhere:
echo ".DS_Store" > ~/.gitignore_global
git config --global core.excludesFile ~/.gitignore_globalIf you really must track an ignored file, git add -f notes.tmp forces it. Use that rarely. Also note that Git tracks files, not folders: an empty directory is invisible to it. Convention is to put a placeholder file such as .gitkeep inside.
Secrets: ignoring is not erasing
If a password reached a commit, ignoring the file afterward does not remove it from history. Anyone with the repository can still read old commits. Treat the secret as exposed: change the password or revoke the key at the source. Cleaning history is possible but is advanced and disruptive, and does not undo exposure that already happened.
Ready-made .gitignore templates for many languages exist in public collections, and they are a good starting point. Read a template before using it so you know what it hides.
Common mistakes
- Adding the rule after committing the file. Remember
git rm --cached. - Forgetting to commit
.gitignore. Teammates then see the clutter you hid. - Trailing spaces in a pattern. They become part of the pattern, and nothing matches.
- Ignoring a file you need. If a lockfile or config template is hidden by a broad pattern, check with
git check-ignore -v. - Believing a private repository makes secrets safe. Access can change; keep secrets out entirely.
Exercise
- Create a repository with
secret.env,debug.logandindex.html. - Write a
.gitignorethat hides the first two without namingindex.html. - Confirm the rules with
git status -sandgit check-ignore -v. - Commit
.gitignoreandindex.html.
Show one possible answer
*.env
*.logSave those lines in .gitignore, then:
git status -s
git check-ignore -v secret.env debug.log
git add .gitignore index.html
git commit -m "Add page and ignore rules"Status before committing shows ?? .gitignore and ?? index.html only.
Next: Discarding changes and unstaging files with git restore.
Key points
- A .gitignore file lists patterns of files Git should not offer to track; commit it so the whole team shares the rules.
- Ignoring only affects untracked files; a file already committed must be untracked with git rm --cached.
- git check-ignore -v tells you which rule is matching a path.
- A trailing slash matches directories, and ! re-includes a file, but not inside an ignored directory.
- Ignoring a file does not remove it from past history, so a committed secret must be treated as exposed.