Documentation/git-status.txt

   1 git-status(1)
   2 =============
   3
   4 NAME
   5 ----
   6 git-status - Show the working tree status
   7
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 'git status' [<options>...] [--] [<pathspec>...]
  13
  14 DESCRIPTION
  15 -----------
  16 Displays paths that have differences between the index file and the
  17 current HEAD commit, paths that have differences between the working
  18 tree and the index file, and paths in the working tree that are not
  19 tracked by Git (and are not ignored by linkgit:gitignore[5]). The first
  20 are what you _would_ commit by running `git commit`; the second and
  21 third are what you _could_ commit by running 'git add' before running
  22 `git commit`.
  23
  24 OPTIONS
  25 -------
  26
  27 -s::
  28 --short::
  29         Give the output in the short-format.
  30
  31 -b::
  32 --branch::
  33         Show the branch and tracking info even in short-format.
  34
  35 --porcelain::
  36         Give the output in an easy-to-parse format for scripts.
  37         This is similar to the short output, but will remain stable
  38         across Git versions and regardless of user configuration. See
  39         below for details.
  40
  41 --long::
  42         Give the output in the long-format. This is the default.
  43
  44 -v::
  45 --verbose::
  46         In addition to the names of files that have been changed, also
  47         show the textual changes that are staged to be committed
  48         (i.e., like the output of `git diff --cached`). If `-v` is specified
  49         twice, then also show the changes in the working tree that
  50         have not yet been staged (i.e., like the output of `git diff`).
  51
  52 -u[<mode>]::
  53 --untracked-files[=<mode>]::
  54         Show untracked files.
  55 +
  56 The mode parameter is used to specify the handling of untracked files.
  57 It is optional: it defaults to 'all', and if specified, it must be
  58 stuck to the option (e.g. `-uno`, but not `-u no`).
  59 +
  60 The possible options are:
  61 +
  62         - 'no'     - Show no untracked files.
  63         - 'normal' - Shows untracked files and directories.
  64         - 'all'    - Also shows individual files in untracked directories.
  65 +
  66 When `-u` option is not used, untracked files and directories are
  67 shown (i.e. the same as specifying `normal`), to help you avoid
  68 forgetting to add newly created files.  Because it takes extra work
  69 to find untracked files in the filesystem, this mode may take some
  70 time in a large working tree.
  71 Consider enabling untracked cache and split index if supported (see
  72 `git update-index --untracked-cache` and `git update-index
  73 --split-index`), Otherwise you can use `no` to have `git status`
  74 return more quickly without showing untracked files.
  75 +
  76 The default can be changed using the status.showUntrackedFiles
  77 configuration variable documented in linkgit:git-config[1].
  78
  79 --ignore-submodules[=<when>]::
  80         Ignore changes to submodules when looking for changes. <when> can be
  81         either "none", "untracked", "dirty" or "all", which is the default.
  82         Using "none" will consider the submodule modified when it either contains
  83         untracked or modified files or its HEAD differs from the commit recorded
  84         in the superproject and can be used to override any settings of the
  85         'ignore' option in linkgit:git-config[1] or linkgit:gitmodules[5]. When
  86         "untracked" is used submodules are not considered dirty when they only
  87         contain untracked content (but they are still scanned for modified
  88         content). Using "dirty" ignores all changes to the work tree of submodules,
  89         only changes to the commits stored in the superproject are shown (this was
  90         the behavior before 1.7.0). Using "all" hides all changes to submodules
  91         (and suppresses the output of submodule summaries when the config option
  92         `status.submoduleSummary` is set).
  93
  94 --ignored::
  95         Show ignored files as well.
  96
  97 -z::
  98         Terminate entries with NUL, instead of LF.  This implies
  99         the `--porcelain` output format if no other format is given.
 100
 101 --column[=<options>]::
 102 --no-column::
 103         Display untracked files in columns. See configuration variable
 104         column.status for option syntax.`--column` and `--no-column`
 105         without options are equivalent to 'always' and 'never'
 106         respectively.
 107
 108
 109 OUTPUT
 110 ------
 111 The output from this command is designed to be used as a commit
 112 template comment.
 113 The default, long format, is designed to be human readable,
 114 verbose and descriptive.  Its contents and format are subject to change
 115 at any time.
 116
 117 The paths mentioned in the output, unlike many other Git commands, are
 118 made relative to the current directory if you are working in a
 119 subdirectory (this is on purpose, to help cutting and pasting). See
 120 the status.relativePaths config option below.
 121
 122 Short Format
 123 ~~~~~~~~~~~~
 124
 125 In the short-format, the status of each path is shown as
 126
 127         XY PATH1 -> PATH2
 128
 129 where `PATH1` is the path in the `HEAD`, and the " `-> PATH2`" part is
 130 shown only when `PATH1` corresponds to a different path in the
 131 index/worktree (i.e. the file is renamed). The `XY` is a two-letter
 132 status code.
 133
 134 The fields (including the `->`) are separated from each other by a
 135 single space. If a filename contains whitespace or other nonprintable
 136 characters, that field will be quoted in the manner of a C string
 137 literal: surrounded by ASCII double quote (34) characters, and with
 138 interior special characters backslash-escaped.
 139
 140 For paths with merge conflicts, `X` and `Y` show the modification
 141 states of each side of the merge. For paths that do not have merge
 142 conflicts, `X` shows the status of the index, and `Y` shows the status
 143 of the work tree.  For untracked paths, `XY` are `??`.  Other status
 144 codes can be interpreted as follows:
 145
 146 * ' ' = unmodified
 147 * 'M' = modified
 148 * 'A' = added
 149 * 'D' = deleted
 150 * 'R' = renamed
 151 * 'C' = copied
 152 * 'U' = updated but unmerged
 153
 154 Ignored files are not listed, unless `--ignored` option is in effect,
 155 in which case `XY` are `!!`.
 156
 157     X          Y     Meaning
 158     -------------------------------------------------
 159               [MD]   not updated
 160     M        [ MD]   updated in index
 161     A        [ MD]   added to index
 162     D         [ M]   deleted from index
 163     R        [ MD]   renamed in index
 164     C        [ MD]   copied in index
 165     [MARC]           index and work tree matches
 166     [ MARC]     M    work tree changed since index
 167     [ MARC]     D    deleted in work tree
 168     -------------------------------------------------
 169     D           D    unmerged, both deleted
 170     A           U    unmerged, added by us
 171     U           D    unmerged, deleted by them
 172     U           A    unmerged, added by them
 173     D           U    unmerged, deleted by us
 174     A           A    unmerged, both added
 175     U           U    unmerged, both modified
 176     -------------------------------------------------
 177     ?           ?    untracked
 178     !           !    ignored
 179     -------------------------------------------------
 180
 181 If -b is used the short-format status is preceded by a line
 182
 183 ## branchname tracking info
 184
 185 Porcelain Format
 186 ~~~~~~~~~~~~~~~~
 187
 188 The porcelain format is similar to the short format, but is guaranteed
 189 not to change in a backwards-incompatible way between Git versions or
 190 based on user configuration. This makes it ideal for parsing by scripts.
 191 The description of the short format above also describes the porcelain
 192 format, with a few exceptions:
 193
 194 1. The user's color.status configuration is not respected; color will
 195    always be off.
 196
 197 2. The user's status.relativePaths configuration is not respected; paths
 198    shown will always be relative to the repository root.
 199
 200 There is also an alternate -z format recommended for machine parsing. In
 201 that format, the status field is the same, but some other things
 202 change.  First, the '\->' is omitted from rename entries and the field
 203 order is reversed (e.g 'from \-> to' becomes 'to from'). Second, a NUL
 204 (ASCII 0) follows each filename, replacing space as a field separator
 205 and the terminating newline (but a space still separates the status
 206 field from the first filename).  Third, filenames containing special
 207 characters are not specially formatted; no quoting or
 208 backslash-escaping is performed.
 209
 210 CONFIGURATION
 211 -------------
 212
 213 The command honors `color.status` (or `status.color` -- they
 214 mean the same thing and the latter is kept for backward
 215 compatibility) and `color.status.<slot>` configuration variables
 216 to colorize its output.
 217
 218 If the config variable `status.relativePaths` is set to false, then all
 219 paths shown are relative to the repository root, not to the current
 220 directory.
 221
 222 If `status.submoduleSummary` is set to a non zero number or true (identical
 223 to -1 or an unlimited number), the submodule summary will be enabled for
 224 the long format and a summary of commits for modified submodules will be
 225 shown (see --summary-limit option of linkgit:git-submodule[1]). Please note
 226 that the summary output from the status command will be suppressed for all
 227 submodules when `diff.ignoreSubmodules` is set to 'all' or only for those
 228 submodules where `submodule.<name>.ignore=all`. To also view the summary for
 229 ignored submodules you can either use the --ignore-submodules=dirty command
 230 line option or the 'git submodule summary' command, which shows a similar
 231 output but does not honor these settings.
 232
 233 SEE ALSO
 234 --------
 235 linkgit:gitignore[5]
 236
 237 GIT
 238 ---
 239 Part of the linkgit:git[1] suite