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