Skip to content
Permalink
Browse files
Merge branch 'jh/status-v2-porcelain'
Enhance "git status --porcelain" output by collecting more data on
the state of the index and the working tree files, which may
further be used to teach git-prompt (in contrib/) to make fewer
calls to git.

* jh/status-v2-porcelain:
  status: unit tests for --porcelain=v2
  test-lib-functions.sh: add lf_to_nul helper
  git-status.txt: describe --porcelain=v2 format
  status: print branch info with --porcelain=v2 --branch
  status: print per-file porcelain v2 status data
  status: collect per-file data for --porcelain=v2
  status: support --porcelain[=<version>]
  status: cleanup API to wt_status_print
  status: rename long-format print routines
  • Loading branch information
gitster committed Sep 9, 2016
2 parents d0b61dc + 888525d commit 00d27937bf0348e7da615f04b65f535a58e096c1
Showing 7 changed files with 1,306 additions and 112 deletions.
@@ -32,11 +32,14 @@ OPTIONS
--branch::
Show the branch and tracking info even in short-format.

--porcelain::
--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 +99,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::
@@ -180,12 +183,12 @@ in which case `XY` are `!!`.

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 +210,124 @@ field from the first filename). Third, filenames containing special
characters are not specially formatted; no quoting or
backslash-escaping is performed.

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.

Otherwise, all pathnames will be "C-quoted" if they contain any tab,
linefeed, double quote, or backslash characters. In C-quoting, these
characters will be replaced with the corresponding C-style escape
sequences and the resulting pathname will be double quoted.


CONFIGURATION
-------------

@@ -142,14 +142,24 @@ static int show_ignored_in_status, have_option_m;
static const char *only_include_assumed;
static struct strbuf message = STRBUF_INIT;

static enum status_format {
STATUS_FORMAT_NONE = 0,
STATUS_FORMAT_LONG,
STATUS_FORMAT_SHORT,
STATUS_FORMAT_PORCELAIN,
static enum wt_status_format status_format = STATUS_FORMAT_UNSPECIFIED;

STATUS_FORMAT_UNSPECIFIED
} status_format = STATUS_FORMAT_UNSPECIFIED;
static int opt_parse_porcelain(const struct option *opt, const char *arg, int unset)
{
enum wt_status_format *value = (enum wt_status_format *)opt->value;
if (unset)
*value = STATUS_FORMAT_NONE;
else if (!arg)
*value = STATUS_FORMAT_PORCELAIN;
else if (!strcmp(arg, "v1") || !strcmp(arg, "1"))
*value = STATUS_FORMAT_PORCELAIN;
else if (!strcmp(arg, "v2") || !strcmp(arg, "2"))
*value = STATUS_FORMAT_PORCELAIN_V2;
else
die("unsupported porcelain version '%s'", arg);

return 0;
}

static int opt_parse_m(const struct option *opt, const char *arg, int unset)
{
@@ -500,24 +510,13 @@ static int run_status(FILE *fp, const char *index_file, const char *prefix, int
s->fp = fp;
s->nowarn = nowarn;
s->is_initial = get_sha1(s->reference, sha1) ? 1 : 0;
if (!s->is_initial)
hashcpy(s->sha1_commit, sha1);
s->status_format = status_format;
s->ignore_submodule_arg = ignore_submodule_arg;

wt_status_collect(s);

switch (status_format) {
case STATUS_FORMAT_SHORT:
wt_shortstatus_print(s);
break;
case STATUS_FORMAT_PORCELAIN:
wt_porcelain_print(s);
break;
case STATUS_FORMAT_UNSPECIFIED:
die("BUG: finalize_deferred_config() should have been called");
break;
case STATUS_FORMAT_NONE:
case STATUS_FORMAT_LONG:
wt_status_print(s);
break;
}
wt_status_print(s);

return s->commitable;
}
@@ -1099,7 +1098,7 @@ static const char *read_commit_message(const char *name)
* is not in effect here.
*/
static struct status_deferred_config {
enum status_format status_format;
enum wt_status_format status_format;
int show_branch;
} status_deferred_config = {
STATUS_FORMAT_UNSPECIFIED,
@@ -1109,6 +1108,7 @@ static struct status_deferred_config {
static void finalize_deferred_config(struct wt_status *s)
{
int use_deferred_config = (status_format != STATUS_FORMAT_PORCELAIN &&
status_format != STATUS_FORMAT_PORCELAIN_V2 &&
!s->null_termination);

if (s->null_termination) {
@@ -1336,9 +1336,9 @@ int cmd_status(int argc, const char **argv, const char *prefix)
N_("show status concisely"), STATUS_FORMAT_SHORT),
OPT_BOOL('b', "branch", &s.show_branch,
N_("show branch information")),
OPT_SET_INT(0, "porcelain", &status_format,
N_("machine-readable output"),
STATUS_FORMAT_PORCELAIN),
{ OPTION_CALLBACK, 0, "porcelain", &status_format,
N_("version"), N_("machine-readable output"),
PARSE_OPT_OPTARG, opt_parse_porcelain },
OPT_SET_INT(0, "long", &status_format,
N_("show status in long format (default)"),
STATUS_FORMAT_LONG),
@@ -1380,7 +1380,13 @@ int cmd_status(int argc, const char **argv, const char *prefix)
fd = hold_locked_index(&index_lock, 0);

s.is_initial = get_sha1(s.reference, sha1) ? 1 : 0;
if (!s.is_initial)
hashcpy(s.sha1_commit, sha1);

s.ignore_submodule_arg = ignore_submodule_arg;
s.status_format = status_format;
s.verbose = verbose;

wt_status_collect(&s);

if (0 <= fd)
@@ -1389,23 +1395,7 @@ int cmd_status(int argc, const char **argv, const char *prefix)
if (s.relative_paths)
s.prefix = prefix;

switch (status_format) {
case STATUS_FORMAT_SHORT:
wt_shortstatus_print(&s);
break;
case STATUS_FORMAT_PORCELAIN:
wt_porcelain_print(&s);
break;
case STATUS_FORMAT_UNSPECIFIED:
die("BUG: finalize_deferred_config() should have been called");
break;
case STATUS_FORMAT_NONE:
case STATUS_FORMAT_LONG:
s.verbose = verbose;
s.ignore_submodule_arg = ignore_submodule_arg;
wt_status_print(&s);
break;
}
wt_status_print(&s);
return 0;
}

@@ -232,4 +232,25 @@ test_expect_success 'status --branch with detached HEAD' '
test_i18ncmp expected actual
'

## Duplicate the above test and verify --porcelain=v1 arg parsing.
test_expect_success 'status --porcelain=v1 --branch with detached HEAD' '
git reset --hard &&
git checkout master^0 &&
git status --branch --porcelain=v1 >actual &&
cat >expected <<-EOF &&
## HEAD (no branch)
?? .gitconfig
?? actual
?? expect
?? expected
?? mdconflict/
EOF
test_i18ncmp expected actual
'

## Verify parser error on invalid --porcelain argument.
test_expect_success 'status --porcelain=bogus' '
test_must_fail git status --porcelain=bogus
'

test_done

0 comments on commit 00d2793

Please sign in to comment.