This topic illustrates how to avoid adding unwanted files (or file changes) in a Git repo. There are several ways (global or local
git update-index --assume-unchanged, and
git update-index --skip-tree), but keep in mind Git is managing content, which means: ignoring actually ignores a folder content (i.e. files). An empty folder would be ignored by default, since it cannot be added anyway.
You can make Git ignore certain files and directories — that is, exclude them from being tracked by Git — by creating one or more
.gitignore files in your repository.
In software projects,
.gitignore typically contains a listing of files and/or directories that are generated during the build process or at runtime. Entries in the
.gitignore file may include names or paths pointing to:
When created in the top level directory, the rules will apply recursively to all files and sub-directories throughout the entire repository. When created in a sub-directory, the rules will apply to that specific directory and its sub-directories.
When a file or directory is ignored, it will not be:
git add -A
In the unusual case that you need to ignore tracked files, special care should be taken. See: Ignore files that have already been committed to a Git repository.
Here are some generic examples of rules in a
.gitignore file, based on glob file patterns:
# Lines starting with `#` are comments. # Ignore files called 'file.ext' file.ext # Comments can't be on the same line as rules! # The following line ignores files called 'file.ext # not a comment' file.ext # not a comment # Ignoring files with full path. # This matches files in the root directory and subdirectories too. # i.e. otherfile.ext will be ignored anywhere on the tree. dir/otherdir/file.ext otherfile.ext # Ignoring directories # Both the directory itself and its contents will be ignored. bin/ gen/ # Glob pattern can also be used here to ignore paths with certain characters. # For example, the below rule will match both build/ and Build/ [bB]uild/ # Without the trailing slash, the rule will match a file and/or # a directory, so the following would ignore both a file named `gen` # and a directory named `gen`, as well as any contents of that directory bin gen # Ignoring files by extension # All files with these extensions will be ignored in # this directory and all its sub-directories. *.apk *.class # It's possible to combine both forms to ignore files with certain # extensions in certain directories. The following rules would be # redundant with generic rules defined above. java/*.apk gen/*.class # To ignore files only at the top level directory, but not in its # subdirectories, prefix the rule with a `/` /*.apk /*.class # To ignore any directories named DirectoryA # in any depth use ** before DirectoryA # Do not forget the last /, # Otherwise it will ignore all files named DirectoryA, rather than directories **/DirectoryA/ # This would ignore # DirectoryA/ # DirectoryB/DirectoryA/ # DirectoryC/DirectoryB/DirectoryA/ # It would not ignore a file named DirectoryA, at any level # To ignore any directory named DirectoryB within a # directory named DirectoryA with any number of # directories in between, use ** between the directories DirectoryA/**/DirectoryB/ # This would ignore # DirectoryA/DirectoryB/ # DirectoryA/DirectoryQ/DirectoryB/ # DirectoryA/DirectoryQ/DirectoryW/DirectoryB/ # To ignore a set of files, wildcards can be used, as can be seen above. # A sole '*' will ignore everything in your folder, including your .gitignore file. # To exclude specific files when using wildcards, negate them. # So they are excluded from the ignore list: !.gitignore # Use the backslash as escape character to ignore files with a hash (#) # (supported since 220.127.116.11) \#*#
.gitignore files are standard across various languages, so to get started, here is set of sample
.gitignore files listed by language from which to clone or copy/modify into your project. Alternatively, for a fresh project you may consider auto-generating a starter file using an online tool.
.gitignore files are intended to be committed as part of the repository. If you want to ignore certain files without committing the ignore rules, here are some options:
.git/info/excludefile (using the same syntax as
.gitignore). The rules will be global in the scope of the repository;
Furthermore, you can ignore local changes to tracked files without changing the global git configuration with:
git update-index --skip-worktree [<file>...]: for minor local modifications
git update-index --assume-unchanged [<file>...]: for production ready, non-changing files upstream
See more details on differences between the latter flags and the
git update-index documentation for further options.
You can use
git clean -X to cleanup ignored files:
git clean -Xn #display a list of ignored files git clean -Xf #remove the previously displayed files
-X (caps) cleans up only ignored files. Use
-x (no caps) to also remove untracked files.
git clean documentation for more details.
See the Git manual for more details.
If you ignore files by using a pattern but have exceptions, prefix an exclamation mark(!) to the exception. For example:
The above example instructs Git to ignore all files with the
.txt extension except for files named
If the file is in an ignored folder, you can NOT re-include it so easily:
In this example all .txt files in the folder would remain ignored.
The right way is re-include the folder itself on a separate line, then ignore all files in
*, finally re-include the
folder, as the following:
!folder/ folder/* !folder/*.txt
Note: For file names beginning with an exclamation mark, add two exclamation marks or escape with the
To have Git ignore certain files across all repositories you can create a global .gitignore with the following command in your terminal or command prompt:
$ git config --global core.excludesfile <Path_To_Global_gitignore_file>
Git will now use this in addition to each repository's own .gitignore file. Rules for this are:
.gitignorefile explicitly includes a file while the global
.gitignoreignores it, the local
.gitignoretakes priority (the file will be included)
.gigignoremust be loaded on all machines or at least include it, as the ignored files will be pushed up to the repo while the PC with the global
.gitignorewouldn't update it. This is why a repo specific
.gitignoreis a better idea than a global one if the project is worked on by a team
This file is a good place to keep platform, machine or user specific ignores, e.g. OSX
Thumbs.db or Vim
*.ext.swp ignores if you don't want to keep those in the repository. So one team member working on OS X can add all
_MACOSX (which is actually useless), while another team member on Windows can ignore all
If you have already added a file to your Git repository and now want to stop tracking it (so that it won't be present in future commits), you can remove it from the index:
git rm --cached <file>
This will remove the file from the repository and prevent further changes from being tracked by Git. The
--cached option will make sure that the file is not physically deleted.
Note that previously added contents of the file will still be visible via the Git history.
Keep in mind that if anyone else pulls from the repository after you removed the file from the index, their copy will be physically deleted.
You can make Git pretend that the working directory version of the file is up to date and read the index version instead (thus ignoring changes in it) with "skip worktree" bit:
git update-index --skip-worktree <file>
Writing is not affected by this bit, content safety is still first priority. You will never lose your precious ignored changes; on the other hand this bit conflicts with stashing: to remove this bit, use
git update-index --no-skip-worktree <file>
It is sometimes wrongly recommended to lie to Git and have it assume that file is unchanged without examining it. It looks at first glance as ignoring any further changes to the file, without removing it from its index:
git update-index --assume-unchanged <file>
This will force git to ignore any change made in the file (keep in mind that if you pull any changes to this file, or you stash it, your ignored changes will be lost)
If you want git to "care" about this file again, run the following command:
git update-index --no-assume-unchanged <file>
git check-ignore command reports on files ignored by Git.
You can pass filenames on the command line, and
git check-ignore will list the filenames that are ignored. For example:
$ cat .gitignore *.o $ git check-ignore example.o Readme.md example.o
Here, only *.o files are defined in .gitignore, so Readme.md is not listed in the output of
If you want to see line of which .gitignore is responsible for ignoring a file, add -v to the git check-ignore command:
$ git check-ignore -v example.o Readme.md .gitignore:1:*.o example.o
Suppose you have a repository structure like this:
examples/ output.log src/ <files not shown> output.log README.md
output.log in the examples directory is valid and required for the project to gather an understanding while the one beneath
src/ is created while debugging and should not be in the history or part of the repository.
There are two ways to ignore this file. You can place an absolute path into the
.gitignore file at the root of the working directory:
# /.gitignore src/output.log
Alternatively, you can create a
.gitignore file in the
src/ directory and ignore the file that is relative to this
# /src/.gitignore output.log
To ignore a file
foo.txt in any directory you should just write its name:
foo.txt # matches all files 'foo.txt' in any directory
If you want to ignore the file only in part of the tree, you can specify the subdirectories of a specific directory with
bar/**/foo.txt # matches all files 'foo.txt' in 'bar' and all subdirectories
Or you can create a
.gitignore file in the
bar/ directory. Equivalent to the previous example would be creating file
bar/.gitignore with these contents:
foo.txt # matches all files 'foo.txt' in any directory under bar/
.gitignore ignores files locally, but it is intended to be committed to the repository and shared with other contributors and users. You can set a global
.gitignore, but then all your repositories would share those settings.
If you want to ignore certain files in a repository locally and not make the file part of any repository, edit
.git/info/exclude inside your repository.
# these files are only ignored on this repo # these rules are not shared with anyone # as they are personal gtk_tests.py gui/gtk/tests/* localhost pushReports.py server/
If you are unsure which rules to list in your
.gitignore file, or you just want to add generally accepted exceptions to your project, you can choose or generate a
Many hosting services such as GitHub and BitBucket offer the ability to generate
.gitignore files based upon the programming languages and IDEs you may be using:
Sometimes you want to have a file held in Git but ignore subsequent changes.
Tell Git to ignore changes to a file or directory using
git update-index --assume-unchanged my-file.txt
The above command instructs Git to assume
my-file.txt hasn't been changed, and not to check or report changes. The file is still present in the repository.
This can be useful for providing defaults and allowing local environment overrides, e.g.:
# create a file with some values in cat <<EOF MYSQL_USER=app MYSQL_PASSWORD=FIXME_SECRET_PASSWORD EOF > .env # commit to Git git add .env git commit -m "Adding .env template" # ignore future changes to .env git update-index --assume-unchanged .env # update your password vi .env # no changes! git status
Sometimes you may want to have local changes in a file you don't want to commit or publish. Ideally local settings should be concentrated in a separate file that can be placed into
.gitignore, but sometimes as a short-term solution it can be helpful to have something local in a checked-in file.
You can make Git "unsee" those lines using clean filter. They won't even show up in diffs.
Suppose here is snippet from file
struct settings s; s.host = "localhost"; s.port = 5653; s.auth = 1; s.port = 15653; // NOCOMMIT s.debug = 1; // NOCOMMIT s.auth = 0; // NOCOMMIT
You don't want to publish
NOCOMMIT lines anywhere.
Create "nocommit" filter by adding this to Git config file like
[filter "nocommit"] clean=grep -v NOCOMMIT
Add (or create) this to
And your NOCOMMIT lines are hidden from Git.
.git/info/exclude work only for untracked files.
To set ignore flag on a tracked file, use the command update-index:
git update-index --skip-worktree myfile.c
To revert this, use:
git update-index --no-skip-worktree myfile.c
You can add this snippet to your global git config to have more convenient
git unhide and
git hidden commands:
[alias] hide = update-index --skip-worktree unhide = update-index --no-skip-worktree hidden = "!git ls-files -v | grep ^[hsS] | cut -c 3-"
You can also use the option --assume-unchanged with the update-index function
git update-index --assume-unchanged <file>
If you want to watch this file again for the changes, use
git update-index --no-assume-unchanged <file>
When --assume-unchanged flag is specified, the user promises not to change the file and allows Git to assume that the working tree file matches what is recorded in the index.Git will fail in case it needs to modify this file in the index e.g. when merging in a commit; thus, in case the assumed-untracked file is changed upstream, you will need to handle the situation manually.The focus lies on performance in this case.
While --skip-worktree flag is useful when you instruct git not to touch a specific file ever because the file is going to be changed locally and you don't want to accidentally commit the changes (i.e configuration/properties file configured for a particular environment). Skip-worktree takes precedence over assume-unchanged when both are set.
Sometimes it happens that a file was being tracked by git, but in a later point in time was added to .gitignore, in order to stop tracking it. It's a very common scenario to forget to clean up such files before its addition to .gitignore. In this case, the old file will still be hanging around in the repository.
To fix this problem, one could perform a "dry-run" removal of everything in the repository, followed by re-adding all the files back. As long as you don't have pending changes and the
--cached parameter is passed, this command is fairly safe to run:
# Remove everything from the index (the files will stay in the file system) $ git rm -r --cached . # Re-add everything (they'll be added in the current state, changes included) $ git add . # Commit, if anything changed. You should see only deletions $ git commit -m 'Remove all files that are in the .gitignore' # Update the remote $ git push origin master
It is not possible to add and commit an empty folder in Git due to the fact that Git manages files and attaches their directory to them, which slims down commits and improves speed. To get around this, there are two methods:
One hack to get around this is to use a
.gitkeep file to register the folder for Git. To do this, just create the required directory and add a
.gitkeep file to the folder. This file is blank and doesn't serve any purpose other than to just register the folder. To do this in Windows (which has awkward file naming conventions) just open git bash in the directory and run the command:
$ touch .gitkeep
This command just makes a blank
.gitkeep file in the current directory
Another hack for this is very similar to the above and the same steps can be followed, but instead of a
.gitkeep, just use a
dummy.txt instead. This has the added bonus of being able to easily create it in Windows using the context menu. And you get to leave funny messages in them too.You can also use
.gitkeep file to track the empty directory.
.gitkeep normally is an empty file that is added to track the empty directoy.
You can list all files ignored by git in current directory with command:
git status --ignored
So if we have repository structure like this:
.git .gitignore ./example_1 ./dir/example_2 ./example_2
...and .gitignore file containing:
...than result of the command will be:
$ git status --ignored On branch master Initial commit Untracked files: (use "git add <file>..." to include in what will be committed) .gitignore .example_1 Ignored files: (use "git add -f <file>..." to include in what will be committed) dir/ example_2
If you want to list recursively ignored files in directories, you have to use additional parameter -
Result will look like this:
$ git status --ignored --untracked-files=all On branch master Initial commit Untracked files: (use "git add <file>..." to include in what will be committed) .gitignore example_1 Ignored files: (use "git add -f <file>..." to include in what will be committed) dir/example_2 example_2