gitignore(5) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | PATTERN FORMAT | CONFIGURATION | NOTES | EXAMPLES | SEE ALSO | GIT | COLOPHON

GITIGNORE(5)                   Git Manual                   GITIGNORE(5)

NAME         top

       gitignore - Specifies intentionally untracked files to ignore

SYNOPSIS         top

       $XDG_CONFIG_HOME/git/ignore, $GIT_DIR/info/exclude, .gitignore

DESCRIPTION         top

       A gitignore file specifies intentionally untracked files that Git
       should ignore. Files already tracked by Git are not affected; see
       the NOTES below for details.

       Each line in a gitignore file specifies a pattern. When deciding
       whether to ignore a path, Git normally checks gitignore patterns
       from multiple sources, with the following order of precedence,
       from highest to lowest (within one level of precedence, the last
       matching pattern decides the outcome):

       •   Patterns read from the command line for those commands that
           support them.

       •   Patterns read from a .gitignore file in the same directory as
           the path, or in any parent directory, with patterns in the
           higher level files (up to the toplevel of the work tree)
           being overridden by those in lower level files down to the
           directory containing the file. These patterns match relative
           to the location of the .gitignore file. A project normally
           includes such .gitignore files in its repository, containing
           patterns for files generated as part of the project build.

       •   Patterns read from $GIT_DIR/info/exclude.

       •   Patterns read from the file specified by the configuration
           variable core.excludesFile.

       Which file to place a pattern in depends on how the pattern is
       meant to be used.

       •   Patterns which should be version-controlled and distributed
           to other repositories via clone (i.e., files that all
           developers will want to ignore) should go into a .gitignore
           file.

       •   Patterns which are specific to a particular repository but
           which do not need to be shared with other related
           repositories (e.g., auxiliary files that live inside the
           repository but are specific to one user’s workflow) should go
           into the $GIT_DIR/info/exclude file.

       •   Patterns which a user wants Git to ignore in all situations
           (e.g., backup or temporary files generated by the user’s
           editor of choice) generally go into a file specified by
           core.excludesFile in the user’s ~/.gitconfig. Its default
           value is $XDG_CONFIG_HOME/git/ignore. If $XDG_CONFIG_HOME is
           either not set or empty, $HOME/.config/git/ignore is used
           instead.

       The underlying Git plumbing tools, such as git ls-files and git
       read-tree, read gitignore patterns specified by command-line
       options, or from files specified by command-line options.
       Higher-level Git tools, such as git status and git add, use
       patterns from the sources specified above.

PATTERN FORMAT         top

       •   A blank line matches no files, so it can serve as a separator
           for readability.

       •   A line starting with # serves as a comment. Put a backslash
           ("\") in front of the first hash for patterns that begin with
           a hash.

       •   Trailing spaces are ignored unless they are quoted with
           backslash ("\").

       •   An optional prefix "!" which negates the pattern; any
           matching file excluded by a previous pattern will become
           included again. It is not possible to re-include a file if a
           parent directory of that file is excluded. Git doesn’t list
           excluded directories for performance reasons, so any patterns
           on contained files have no effect, no matter where they are
           defined. Put a backslash ("\") in front of the first "!" for
           patterns that begin with a literal "!", for example,
           "\!important!.txt".

       •   The slash / is used as the directory separator. Separators
           may occur at the beginning, middle or end of the .gitignore
           search pattern.

       •   If there is a separator at the beginning or middle (or both)
           of the pattern, then the pattern is relative to the directory
           level of the particular .gitignore file itself. Otherwise the
           pattern may also match at any level below the .gitignore
           level.

       •   If there is a separator at the end of the pattern then the
           pattern will only match directories, otherwise the pattern
           can match both files and directories.

       •   For example, a pattern doc/frotz/ matches doc/frotz
           directory, but not a/doc/frotz directory; however frotz/
           matches frotz and a/frotz that is a directory (all paths are
           relative from the .gitignore file).

       •   An asterisk "*" matches anything except a slash. The
           character "?" matches any one character except "/". The range
           notation, e.g.  [a-zA-Z], can be used to match one of the
           characters in a range. See fnmatch(3) and the FNM_PATHNAME
           flag for a more detailed description.

       Two consecutive asterisks ("**") in patterns matched against full
       pathname may have special meaning:

       •   A leading "**" followed by a slash means match in all
           directories. For example, "**/foo" matches file or directory
           "foo" anywhere, the same as pattern "foo". "**/foo/bar"
           matches file or directory "bar" anywhere that is directly
           under directory "foo".

       •   A trailing "/**" matches everything inside. For example,
           "abc/**" matches all files inside directory "abc", relative
           to the location of the .gitignore file, with infinite depth.

       •   A slash followed by two consecutive asterisks then a slash
           matches zero or more directories. For example, "a/**/b"
           matches "a/b", "a/x/b", "a/x/y/b" and so on.

       •   Other consecutive asterisks are considered regular asterisks
           and will match according to the previous rules.

CONFIGURATION         top

       The optional configuration variable core.excludesFile indicates a
       path to a file containing patterns of file names to exclude,
       similar to $GIT_DIR/info/exclude. Patterns in the exclude file
       are used in addition to those in $GIT_DIR/info/exclude.

NOTES         top

       The purpose of gitignore files is to ensure that certain files
       not tracked by Git remain untracked.

       To stop tracking a file that is currently tracked, use git rm
       --cached.

EXAMPLES         top

       •   The pattern hello.*  matches any file or folder whose name
           begins with hello.. If one wants to restrict this only to the
           directory and not in its subdirectories, one can prepend the
           pattern with a slash, i.e.  /hello.*; the pattern now matches
           hello.txt, hello.c but not a/hello.java.

       •   The pattern foo/ will match a directory foo and paths
           underneath it, but will not match a regular file or a
           symbolic link foo (this is consistent with the way how
           pathspec works in general in Git)

       •   The pattern doc/frotz and /doc/frotz have the same effect in
           any .gitignore file. In other words, a leading slash is not
           relevant if there is already a middle slash in the pattern.

       •   The pattern "foo/*", matches "foo/test.json" (a regular
           file), "foo/bar" (a directory), but it does not match
           "foo/bar/hello.c" (a regular file), as the asterisk in the
           pattern does not match "bar/hello.c" which has a slash in it.

               $ git status
               [...]
               # Untracked files:
               [...]
               #       Documentation/foo.html
               #       Documentation/gitignore.html
               #       file.o
               #       lib.a
               #       src/internal.o
               [...]
               $ cat .git/info/exclude
               # ignore objects and archives, anywhere in the tree.
               *.[oa]
               $ cat Documentation/.gitignore
               # ignore generated html files,
               *.html
               # except foo.html which is maintained by hand
               !foo.html
               $ git status
               [...]
               # Untracked files:
               [...]
               #       Documentation/foo.html
               [...]

       Another example:

               $ cat .gitignore
               vmlinux*
               $ ls arch/foo/kernel/vm*
               arch/foo/kernel/vmlinux.lds.S
               $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore

       The second .gitignore prevents Git from ignoring
       arch/foo/kernel/vmlinux.lds.S.

       Example to exclude everything except a specific directory foo/bar
       (note the /* - without the slash, the wildcard would also exclude
       everything within foo/bar):

               $ cat .gitignore
               # exclude everything except directory foo/bar
               /*
               !/foo
               /foo/*
               !/foo/bar

SEE ALSO         top

       git-rm(1), gitrepository-layout(5), git-check-ignore(1)

GIT         top

       Part of the git(1) suite

COLOPHON         top

       This page is part of the git (Git distributed version control
       system) project.  Information about the project can be found at
       ⟨http://git-scm.com/⟩.  If you have a bug report for this manual
       page, see ⟨http://git-scm.com/community⟩.  This page was obtained
       from the project's upstream Git repository
       ⟨https://github.com/git/git.git⟩ on 2021-04-01.  (At that time,
       the date of the most recent commit that was found in the
       repository was 2021-03-30.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

Git 2.31.1.163.ga65ce7         04/01/2021                   GITIGNORE(5)

Pages that refer to this page: git(1)git-check-ignore(1)git-clean(1)git-commit(1)git-commit-tree(1)git-config(1)git-init(1)git-log(1)git-ls-files(1)git-read-tree(1)git-show(1)git-sparse-checkout(1)git-status(1)gitattributes(5)gitrepository-layout(5)gitfaq(7)