Skip to content

Commit

Permalink
Merge branch 'jh/status-v2-porcelain'
Browse files Browse the repository at this point in the history 
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
gitster committed Sep 9, 2016
2 parents d0b61dc + 888525d commit 00d2793
Show file tree
Hide file tree
Showing 7 changed files with 1,306 additions and 112 deletions.
133 changes: 127 additions & 6 deletions Documentation/git-status.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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::
Expand Down Expand Up @@ -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
Expand All @@ -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
-------------

Expand Down
78 changes: 34 additions & 44 deletions builtin/commit.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
{
Expand Down Expand Up @@ -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;
}
Expand Down Expand Up @@ -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,
Expand All @@ -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) {
Expand Down Expand Up @@ -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),
Expand Down Expand Up @@ -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)
Expand All @@ -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;
}

Expand Down
21 changes: 21 additions & 0 deletions t/t7060-wtstatus.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading

0 comments on commit 00d2793

Please sign in to comment.