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 --show-stash::
  36         Show the number of entries currently stashed away.
  37
  38 --porcelain[=<version>]::
  39         Give the output in an easy-to-parse format for scripts.
  40         This is similar to the short output, but will remain stable
  41         across Git versions and regardless of user configuration. See
  42         below for details.
  43 +
  44 The version parameter is used to specify the format version.
  45 This is optional and defaults to the original version 'v1' format.
  46
  47 --long::
  48         Give the output in the long-format. This is the default.
  49
  50 -v::
  51 --verbose::
  52         In addition to the names of files that have been changed, also
  53         show the textual changes that are staged to be committed
  54         (i.e., like the output of `git diff --cached`). If `-v` is specified
  55         twice, then also show the changes in the working tree that
  56         have not yet been staged (i.e., like the output of `git diff`).
  57
  58 -u[<mode>]::
  59 --untracked-files[=<mode>]::
  60         Show untracked files.
  61 +
  62 --
  63 The mode parameter is used to specify the handling of untracked files.
  64 It is optional: it defaults to 'all', and if specified, it must be
  65 stuck to the option (e.g. `-uno`, but not `-u no`).
  66
  67 The possible options are:
  68
  69         - 'no'     - Show no untracked files.
  70         - 'normal' - Shows untracked files and directories.
  71         - 'all'    - Also shows individual files in untracked directories.
  72
  73 When `-u` option is not used, untracked files and directories are
  74 shown (i.e. the same as specifying `normal`), to help you avoid
  75 forgetting to add newly created files.  Because it takes extra work
  76 to find untracked files in the filesystem, this mode may take some
  77 time in a large working tree.
  78 Consider enabling untracked cache and split index if supported (see
  79 `git update-index --untracked-cache` and `git update-index
  80 --split-index`), Otherwise you can use `no` to have `git status`
  81 return more quickly without showing untracked files.
  82
  83 The default can be changed using the status.showUntrackedFiles
  84 configuration variable documented in linkgit:git-config[1].
  85 --
  86
  87 --ignore-submodules[=<when>]::
  88         Ignore changes to submodules when looking for changes. <when> can be
  89         either "none", "untracked", "dirty" or "all", which is the default.
  90         Using "none" will consider the submodule modified when it either contains
  91         untracked or modified files or its HEAD differs from the commit recorded
  92         in the superproject and can be used to override any settings of the
  93         'ignore' option in linkgit:git-config[1] or linkgit:gitmodules[5]. When
  94         "untracked" is used submodules are not considered dirty when they only
  95         contain untracked content (but they are still scanned for modified
  96         content). Using "dirty" ignores all changes to the work tree of submodules,
  97         only changes to the commits stored in the superproject are shown (this was
  98         the behavior before 1.7.0). Using "all" hides all changes to submodules
  99         (and suppresses the output of submodule summaries when the config option
 100         `status.submoduleSummary` is set).
 101
 102 --ignored[=<mode>]::
 103         Show ignored files as well.
 104 +
 105 --
 106 The mode parameter is used to specify the handling of ignored files.
 107 It is optional: it defaults to 'traditional'.
 108
 109 The possible options are:
 110
 111         - 'traditional' - Shows ignored files and directories, unless
 112                           --untracked-files=all is specified, in which case
 113                           individual files in ignored directories are
 114                           displayed.
 115         - 'no'          - Show no ignored files.
 116         - 'matching'    - Shows ignored files and directories matching an
 117                           ignore pattern.
 118
 119 When 'matching' mode is specified, paths that explicitly match an
 120 ignored pattern are shown. If a directory matches an ignore pattern,
 121 then it is shown, but not paths contained in the ignored directory. If
 122 a directory does not match an ignore pattern, but all contents are
 123 ignored, then the directory is not shown, but all contents are shown.
 124 --
 125
 126 -z::
 127         Terminate entries with NUL, instead of LF.  This implies
 128         the `--porcelain=v1` output format if no other format is given.
 129
 130 --column[=<options>]::
 131 --no-column::
 132         Display untracked files in columns. See configuration variable
 133         column.status for option syntax.`--column` and `--no-column`
 134         without options are equivalent to 'always' and 'never'
 135         respectively.
 136
 137 --ahead-behind::
 138 --no-ahead-behind::
 139         Display or do not display detailed ahead/behind counts for the
 140         branch relative to its upstream branch.  Defaults to true.
 141
 142 --renames::
 143 --no-renames::
 144         Turn on/off rename detection regardless of user configuration.
 145         See also linkgit:git-diff[1] `--no-renames`.
 146
 147 --find-renames[=<n>]::
 148         Turn on rename detection, optionally setting the similarity
 149         threshold.
 150         See also linkgit:git-diff[1] `--find-renames`.
 151
 152 <pathspec>...::
 153         See the 'pathspec' entry in linkgit:gitglossary[7].
 154
 155 OUTPUT
 156 ------
 157 The output from this command is designed to be used as a commit
 158 template comment.
 159 The default, long format, is designed to be human readable,
 160 verbose and descriptive.  Its contents and format are subject to change
 161 at any time.
 162
 163 The paths mentioned in the output, unlike many other Git commands, are
 164 made relative to the current directory if you are working in a
 165 subdirectory (this is on purpose, to help cutting and pasting). See
 166 the status.relativePaths config option below.
 167
 168 Short Format
 169 ~~~~~~~~~~~~
 170
 171 In the short-format, the status of each path is shown as one of these
 172 forms
 173
 174         XY PATH
 175         XY ORIG_PATH -> PATH
 176
 177 where `ORIG_PATH` is where the renamed/copied contents came
 178 from. `ORIG_PATH` is only shown when the entry is renamed or
 179 copied. The `XY` is a two-letter status code.
 180
 181 The fields (including the `->`) are separated from each other by a
 182 single space. If a filename contains whitespace or other nonprintable
 183 characters, that field will be quoted in the manner of a C string
 184 literal: surrounded by ASCII double quote (34) characters, and with
 185 interior special characters backslash-escaped.
 186
 187 For paths with merge conflicts, `X` and `Y` show the modification
 188 states of each side of the merge. For paths that do not have merge
 189 conflicts, `X` shows the status of the index, and `Y` shows the status
 190 of the work tree.  For untracked paths, `XY` are `??`.  Other status
 191 codes can be interpreted as follows:
 192
 193 * ' ' = unmodified
 194 * 'M' = modified
 195 * 'A' = added
 196 * 'D' = deleted
 197 * 'R' = renamed
 198 * 'C' = copied
 199 * 'U' = updated but unmerged
 200
 201 Ignored files are not listed, unless `--ignored` option is in effect,
 202 in which case `XY` are `!!`.
 203
 204 ....
 205 X          Y     Meaning
 206 -------------------------------------------------
 207          [AMD]   not updated
 208 M        [ MD]   updated in index
 209 A        [ MD]   added to index
 210 D                deleted from index
 211 R        [ MD]   renamed in index
 212 C        [ MD]   copied in index
 213 [MARC]           index and work tree matches
 214 [ MARC]     M    work tree changed since index
 215 [ MARC]     D    deleted in work tree
 216 [ D]        R    renamed in work tree
 217 [ D]        C    copied in work tree
 218 -------------------------------------------------
 219 D           D    unmerged, both deleted
 220 A           U    unmerged, added by us
 221 U           D    unmerged, deleted by them
 222 U           A    unmerged, added by them
 223 D           U    unmerged, deleted by us
 224 A           A    unmerged, both added
 225 U           U    unmerged, both modified
 226 -------------------------------------------------
 227 ?           ?    untracked
 228 !           !    ignored
 229 -------------------------------------------------
 230 ....
 231
 232 Submodules have more state and instead report
 233                 M    the submodule has a different HEAD than
 234                      recorded in the index
 235                 m    the submodule has modified content
 236                 ?    the submodule has untracked files
 237 since modified content or untracked files in a submodule cannot be added
 238 via `git add` in the superproject to prepare a commit.
 239
 240 'm' and '?' are applied recursively. For example if a nested submodule
 241 in a submodule contains an untracked file, this is reported as '?' as well.
 242
 243 If -b is used the short-format status is preceded by a line
 244
 245     ## branchname tracking info
 246
 247 Porcelain Format Version 1
 248 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 249
 250 Version 1 porcelain format is similar to the short format, but is guaranteed
 251 not to change in a backwards-incompatible way between Git versions or
 252 based on user configuration. This makes it ideal for parsing by scripts.
 253 The description of the short format above also describes the porcelain
 254 format, with a few exceptions:
 255
 256 1. The user's color.status configuration is not respected; color will
 257    always be off.
 258
 259 2. The user's status.relativePaths configuration is not respected; paths
 260    shown will always be relative to the repository root.
 261
 262 There is also an alternate -z format recommended for machine parsing. In
 263 that format, the status field is the same, but some other things
 264 change.  First, the '\->' is omitted from rename entries and the field
 265 order is reversed (e.g 'from \-> to' becomes 'to from'). Second, a NUL
 266 (ASCII 0) follows each filename, replacing space as a field separator
 267 and the terminating newline (but a space still separates the status
 268 field from the first filename).  Third, filenames containing special
 269 characters are not specially formatted; no quoting or
 270 backslash-escaping is performed.
 271
 272 Any submodule changes are reported as modified `M` instead of `m` or single `?`.
 273
 274 Porcelain Format Version 2
 275 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 276
 277 Version 2 format adds more detailed information about the state of
 278 the worktree and changed items.  Version 2 also defines an extensible
 279 set of easy to parse optional headers.
 280
 281 Header lines start with "#" and are added in response to specific
 282 command line arguments.  Parsers should ignore headers they
 283 don't recognize.
 284
 285 Branch Headers
 286 ^^^^^^^^^^^^^^
 287
 288 If `--branch` is given, a series of header lines are printed with
 289 information about the current branch.
 290
 291 ....
 292 Line                                     Notes
 293 ------------------------------------------------------------
 294 # branch.oid <commit> | (initial)        Current commit.
 295 # branch.head <branch> | (detached)      Current branch.
 296 # branch.upstream <upstream_branch>      If upstream is set.
 297 # branch.ab +<ahead> -<behind>           If upstream is set and
 298                                          the commit is present.
 299 ------------------------------------------------------------
 300 ....
 301
 302 Changed Tracked Entries
 303 ^^^^^^^^^^^^^^^^^^^^^^^
 304
 305 Following the headers, a series of lines are printed for tracked
 306 entries.  One of three different line formats may be used to describe
 307 an entry depending on the type of change.  Tracked entries are printed
 308 in an undefined order; parsers should allow for a mixture of the 3
 309 line types in any order.
 310
 311 Ordinary changed entries have the following format:
 312
 313     1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>
 314
 315 Renamed or copied entries have the following format:
 316
 317     2 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><score> <path><sep><origPath>
 318
 319 ....
 320 Field       Meaning
 321 --------------------------------------------------------
 322 <XY>        A 2 character field containing the staged and
 323             unstaged XY values described in the short format,
 324             with unchanged indicated by a "." rather than
 325             a space.
 326 <sub>       A 4 character field describing the submodule state.
 327             "N..." when the entry is not a submodule.
 328             "S<c><m><u>" when the entry is a submodule.
 329             <c> is "C" if the commit changed; otherwise ".".
 330             <m> is "M" if it has tracked changes; otherwise ".".
 331             <u> is "U" if there are untracked changes; otherwise ".".
 332 <mH>        The octal file mode in HEAD.
 333 <mI>        The octal file mode in the index.
 334 <mW>        The octal file mode in the worktree.
 335 <hH>        The object name in HEAD.
 336 <hI>        The object name in the index.
 337 <X><score>  The rename or copy score (denoting the percentage
 338             of similarity between the source and target of the
 339             move or copy). For example "R100" or "C75".
 340 <path>      The pathname.  In a renamed/copied entry, this
 341             is the target path.
 342 <sep>       When the `-z` option is used, the 2 pathnames are separated
 343             with a NUL (ASCII 0x00) byte; otherwise, a tab (ASCII 0x09)
 344             byte separates them.
 345 <origPath>  The pathname in the commit at HEAD or in the index.
 346             This is only present in a renamed/copied entry, and
 347             tells where the renamed/copied contents came from.
 348 --------------------------------------------------------
 349 ....
 350
 351 Unmerged entries have the following format; the first character is
 352 a "u" to distinguish from ordinary changed entries.
 353
 354     u <xy> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path>
 355
 356 ....
 357 Field       Meaning
 358 --------------------------------------------------------
 359 <XY>        A 2 character field describing the conflict type
 360             as described in the short format.
 361 <sub>       A 4 character field describing the submodule state
 362             as described above.
 363 <m1>        The octal file mode in stage 1.
 364 <m2>        The octal file mode in stage 2.
 365 <m3>        The octal file mode in stage 3.
 366 <mW>        The octal file mode in the worktree.
 367 <h1>        The object name in stage 1.
 368 <h2>        The object name in stage 2.
 369 <h3>        The object name in stage 3.
 370 <path>      The pathname.
 371 --------------------------------------------------------
 372 ....
 373
 374 Other Items
 375 ^^^^^^^^^^^
 376
 377 Following the tracked entries (and if requested), a series of
 378 lines will be printed for untracked and then ignored items
 379 found in the worktree.
 380
 381 Untracked items have the following format:
 382
 383     ? <path>
 384
 385 Ignored items have the following format:
 386
 387     ! <path>
 388
 389 Pathname Format Notes and -z
 390 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 391
 392 When the `-z` option is given, pathnames are printed as is and
 393 without any quoting and lines are terminated with a NUL (ASCII 0x00)
 394 byte.
 395
 396 Without the `-z` option, pathnames with "unusual" characters are
 397 quoted as explained for the configuration variable `core.quotePath`
 398 (see linkgit:git-config[1]).
 399
 400
 401 CONFIGURATION
 402 -------------
 403
 404 The command honors `color.status` (or `status.color` -- they
 405 mean the same thing and the latter is kept for backward
 406 compatibility) and `color.status.<slot>` configuration variables
 407 to colorize its output.
 408
 409 If the config variable `status.relativePaths` is set to false, then all
 410 paths shown are relative to the repository root, not to the current
 411 directory.
 412
 413 If `status.submoduleSummary` is set to a non zero number or true (identical
 414 to -1 or an unlimited number), the submodule summary will be enabled for
 415 the long format and a summary of commits for modified submodules will be
 416 shown (see --summary-limit option of linkgit:git-submodule[1]). Please note
 417 that the summary output from the status command will be suppressed for all
 418 submodules when `diff.ignoreSubmodules` is set to 'all' or only for those
 419 submodules where `submodule.<name>.ignore=all`. To also view the summary for
 420 ignored submodules you can either use the --ignore-submodules=dirty command
 421 line option or the 'git submodule summary' command, which shows a similar
 422 output but does not honor these settings.
 423
 424 BACKGROUND REFRESH
 425 ------------------
 426
 427 By default, `git status` will automatically refresh the index, updating
 428 the cached stat information from the working tree and writing out the
 429 result. Writing out the updated index is an optimization that isn't
 430 strictly necessary (`status` computes the values for itself, but writing
 431 them out is just to save subsequent programs from repeating our
 432 computation). When `status` is run in the background, the lock held
 433 during the write may conflict with other simultaneous processes, causing
 434 them to fail. Scripts running `status` in the background should consider
 435 using `git --no-optional-locks status` (see linkgit:git[1] for details).
 436
 437 SEE ALSO
 438 --------
 439 linkgit:gitignore[5]
 440
 441 GIT
 442 ---
 443 Part of the linkgit:git[1] suite