summaryrefslogtreecommitdiff
path: root/Documentation/git-status.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/git-status.txt')
-rw-r--r--Documentation/git-status.txt148
1 files changed, 142 insertions, 6 deletions
diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index e1e8f57cdd..d47f198f15 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -32,11 +32,17 @@ OPTIONS
--branch::
Show the branch and tracking info even in short-format.
---porcelain::
+--show-stash::
+ Show the number of entries currently stashed away.
+
+--porcelain[=<version>]::
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.
@@ -96,7 +102,7 @@ configuration variable documented in linkgit:git-config[1].
-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[=<options>]::
--no-column::
@@ -178,14 +184,25 @@ in which case `XY` are `!!`.
! ! 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
@@ -207,6 +224,125 @@ field from the first filename). Third, filenames containing special
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 <commit> | (initial) Current commit.
+ # branch.head <branch> | (detached) Current branch.
+ # branch.upstream <upstream_branch> If upstream is set.
+ # branch.ab +<ahead> -<behind> 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 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>
+
+Renamed or copied entries have the following format:
+
+ 2 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><score> <path><sep><origPath>
+
+ Field Meaning
+ --------------------------------------------------------
+ <XY> 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.
+ <sub> A 4 character field describing the submodule state.
+ "N..." when the entry is not a submodule.
+ "S<c><m><u>" when the entry is a submodule.
+ <c> is "C" if the commit changed; otherwise ".".
+ <m> is "M" if it has tracked changes; otherwise ".".
+ <u> is "U" if there are untracked changes; otherwise ".".
+ <mH> The octal file mode in HEAD.
+ <mI> The octal file mode in the index.
+ <mW> The octal file mode in the worktree.
+ <hH> The object name in HEAD.
+ <hI> The object name in the index.
+ <X><score> 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".
+ <path> The pathname. In a renamed/copied entry, this
+ is the path in the index and in the working tree.
+ <sep> 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.
+ <origPath> The pathname in the commit at HEAD. 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 <xy> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path>
+
+ Field Meaning
+ --------------------------------------------------------
+ <XY> A 2 character field describing the conflict type
+ as described in the short format.
+ <sub> A 4 character field describing the submodule state
+ as described above.
+ <m1> The octal file mode in stage 1.
+ <m2> The octal file mode in stage 2.
+ <m3> The octal file mode in stage 3.
+ <mW> The octal file mode in the worktree.
+ <h1> The object name in stage 1.
+ <h2> The object name in stage 2.
+ <h3> The object name in stage 3.
+ <path> 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:
+
+ ? <path>
+
+Ignored items have the following format:
+
+ ! <path>
+
+### 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
-------------