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