From: Junio C Hamano Date: Wed, 28 Feb 2018 21:37:54 +0000 (-0800) Subject: Merge branch 'sb/status-doc-fix' X-Git-Tag: v2.17.0-rc0~57 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/7676b86ec2a60078ed3eb274d208bf61be3e29a7?ds=inline;hp=-c Merge branch 'sb/status-doc-fix' Docfix. * sb/status-doc-fix: Documentation/git-status: clarify status table for porcelain mode --- 7676b86ec2a60078ed3eb274d208bf61be3e29a7 diff --combined Documentation/git-status.txt index 72bfb87f66,4cb12218ea..f9c91c721e --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@@ -32,17 -32,11 +32,17 @@@ OPTION --branch:: Show the branch and tracking info even in short-format. ---porcelain:: +--show-stash:: + Show the number of entries currently stashed away. + +--porcelain[=]:: Give the output in an easy-to-parse format for scripts. This is similar to the short output, but will remain stable across Git versions and regardless of user configuration. See below for details. ++ +The version parameter is used to specify the format version. +This is optional and defaults to the original version 'v1' format. --long:: Give the output in the long-format. This is the default. @@@ -97,31 -91,12 +97,31 @@@ configuration variable documented in li (and suppresses the output of submodule summaries when the config option `status.submoduleSummary` is set). ---ignored:: +--ignored[=]:: Show ignored files as well. ++ +The mode parameter is used to specify the handling of ignored files. +It is optional: it defaults to 'traditional'. ++ +The possible options are: ++ + - 'traditional' - Shows ignored files and directories, unless + --untracked-files=all is specifed, in which case + individual files in ignored directories are + displayed. + - 'no' - Show no ignored files. + - 'matching' - Shows ignored files and directories matching an + ignore pattern. ++ +When 'matching' mode is specified, paths that explicity match an +ignored pattern are shown. If a directory matches an ignore pattern, +then it is shown, but not paths contained in the ignored directory. If +a directory does not match an ignore pattern, but all contents are +ignored, then the directory is not shown, but all contents are shown. -z:: Terminate entries with NUL, instead of LF. This implies - the `--porcelain` output format if no other format is given. + the `--porcelain=v1` output format if no other format is given. --column[=]:: --no-column:: @@@ -130,8 -105,6 +130,8 @@@ without options are equivalent to 'always' and 'never' respectively. +...:: + See the 'pathspec' entry in linkgit:gitglossary[7]. OUTPUT ------ @@@ -149,15 -122,14 +149,15 @@@ the status.relativePaths config option Short Format ~~~~~~~~~~~~ -In the short-format, the status of each path is shown as +In the short-format, the status of each path is shown as one of these +forms - XY PATH1 -> PATH2 + XY PATH + XY ORIG_PATH -> PATH -where `PATH1` is the path in the `HEAD`, and the " `-> PATH2`" part is -shown only when `PATH1` corresponds to a different path in the -index/worktree (i.e. the file is renamed). The `XY` is a two-letter -status code. +where `ORIG_PATH` is where the renamed/copied contents came +from. `ORIG_PATH` is only shown when the entry is renamed or +copied. The `XY` is a two-letter status code. The fields (including the `->`) are separated from each other by a single space. If a filename contains whitespace or other nonprintable @@@ -184,17 -156,15 +184,17 @@@ in which case `XY` are `!!` X Y Meaning ------------------------------------------------- - [MD] not updated + [AMD] not updated M [ MD] updated in index A [ MD] added to index - D [ M] deleted from index + D deleted from index R [ MD] renamed in index C [ MD] copied in index [MARC] index and work tree matches [ MARC] M work tree changed since index [ MARC] D deleted in work tree + [ D] R renamed in work tree + [ D] C copied in work tree ------------------------------------------------- D D unmerged, both deleted A U unmerged, added by us @@@ -208,25 -178,14 +208,25 @@@ ! ! ignored ------------------------------------------------- +Submodules have more state and instead report + M the submodule has a different HEAD than + recorded in the index + m the submodule has modified content + ? the submodule has untracked files +since modified content or untracked files in a submodule cannot be added +via `git add` in the superproject to prepare a commit. + +'m' and '?' are applied recursively. For example if a nested submodule +in a submodule contains an untracked file, this is reported as '?' as well. + If -b is used the short-format status is preceded by a line -## branchname tracking info + ## branchname tracking info -Porcelain Format -~~~~~~~~~~~~~~~~ +Porcelain Format Version 1 +~~~~~~~~~~~~~~~~~~~~~~~~~~ -The porcelain format is similar to the short format, but is guaranteed +Version 1 porcelain format is similar to the short format, but is guaranteed not to change in a backwards-incompatible way between Git versions or based on user configuration. This makes it ideal for parsing by scripts. The description of the short format above also describes the porcelain @@@ -248,125 -207,6 +248,125 @@@ field from the first filename). Third characters are not specially formatted; no quoting or backslash-escaping is performed. +Any submodule changes are reported as modified `M` instead of `m` or single `?`. + +Porcelain Format Version 2 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Version 2 format adds more detailed information about the state of +the worktree and changed items. Version 2 also defines an extensible +set of easy to parse optional headers. + +Header lines start with "#" and are added in response to specific +command line arguments. Parsers should ignore headers they +don't recognize. + +### Branch Headers + +If `--branch` is given, a series of header lines are printed with +information about the current branch. + + Line Notes + ------------------------------------------------------------ + # branch.oid | (initial) Current commit. + # branch.head | (detached) Current branch. + # branch.upstream If upstream is set. + # branch.ab + - If upstream is set and + the commit is present. + ------------------------------------------------------------ + +### Changed Tracked Entries + +Following the headers, a series of lines are printed for tracked +entries. One of three different line formats may be used to describe +an entry depending on the type of change. Tracked entries are printed +in an undefined order; parsers should allow for a mixture of the 3 +line types in any order. + +Ordinary changed entries have the following format: + + 1 + +Renamed or copied entries have the following format: + + 2 + + Field Meaning + -------------------------------------------------------- + A 2 character field containing the staged and + unstaged XY values described in the short format, + with unchanged indicated by a "." rather than + a space. + A 4 character field describing the submodule state. + "N..." when the entry is not a submodule. + "S" when the entry is a submodule. + is "C" if the commit changed; otherwise ".". + is "M" if it has tracked changes; otherwise ".". + is "U" if there are untracked changes; otherwise ".". + The octal file mode in HEAD. + The octal file mode in the index. + The octal file mode in the worktree. + The object name in HEAD. + The object name in the index. + The rename or copy score (denoting the percentage + of similarity between the source and target of the + move or copy). For example "R100" or "C75". + The pathname. In a renamed/copied entry, this + is the target path. + When the `-z` option is used, the 2 pathnames are separated + with a NUL (ASCII 0x00) byte; otherwise, a tab (ASCII 0x09) + byte separates them. + The pathname in the commit at HEAD or in the index. + This is only present in a renamed/copied entry, and + tells where the renamed/copied contents came from. + -------------------------------------------------------- + +Unmerged entries have the following format; the first character is +a "u" to distinguish from ordinary changed entries. + + u

+ + Field Meaning + -------------------------------------------------------- + A 2 character field describing the conflict type + as described in the short format. + A 4 character field describing the submodule state + as described above. + The octal file mode in stage 1. + The octal file mode in stage 2. + The octal file mode in stage 3. + The octal file mode in the worktree. +

The object name in stage 1. +

The object name in stage 2. +

The object name in stage 3. + The pathname. + -------------------------------------------------------- + +### Other Items + +Following the tracked entries (and if requested), a series of +lines will be printed for untracked and then ignored items +found in the worktree. + +Untracked items have the following format: + + ? + +Ignored items have the following format: + + ! + +### Pathname Format Notes and -z + +When the `-z` option is given, pathnames are printed as is and +without any quoting and lines are terminated with a NUL (ASCII 0x00) +byte. + +Without the `-z` option, pathnames with "unusual" characters are +quoted as explained for the configuration variable `core.quotePath` +(see linkgit:git-config[1]). + + CONFIGURATION ------------- @@@ -390,19 -230,6 +390,19 @@@ ignored submodules you can either use t line option or the 'git submodule summary' command, which shows a similar output but does not honor these settings. +BACKGROUND REFRESH +------------------ + +By default, `git status` will automatically refresh the index, updating +the cached stat information from the working tree and writing out the +result. Writing out the updated index is an optimization that isn't +strictly necessary (`status` computes the values for itself, but writing +them out is just to save subsequent programs from repeating our +computation). When `status` is run in the background, the lock held +during the write may conflict with other simultaneous processes, causing +them to fail. Scripts running `status` in the background should consider +using `git --no-optional-locks status` (see linkgit:git[1] for details). + SEE ALSO -------- linkgit:gitignore[5]