From: Jeff Hostetler Date: Fri, 05 Aug 2016 18:27:17 GMT Subject: Re: [PATCH v4 7/8] git-status.txt: describe --porcelain=v2 format Message-ID: <57A4DA85.2010809@jeffhostetler.com> In-Reply-To: On 08/05/2016 01:50 PM, Junio C Hamano wrote: > Jeff Hostetler writes: > >> +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. > > In an earlier review I made a noise about "branch.head", but reading > this together with others in a context, "branch.head" is good and I > do not see a need to bikeshed it into "branch.name". right. >> + # 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 6 character octal file mode in the HEAD. > > We do want "octal" to be spelled out, but I doubt that we want to > guarantee to the reading scripts that this will always be 6 > characters. good point. "octal" is sufficient. >> + The octal file mode in the index. >> + The octal file mode in the worktree. >> + The SHA1 value in the HEAD. >> + The SHA1 value in the index. > > Please avoid inventing a word "SHA1 value" that does not appear in > Documentation/glossary-content.txt; s/SHA1 value/object name/g. > This comment applies to the desciption for "U" lines below, too. ok. >> + The rename or copied percentage score. For example "R100" >> + or "C75". > > Documentation/diff-format.txt seems to call this differently. > > The rename or copy "score" number, e.g. "R100", "C75". > > perhaps? right, this is the same score. >> + The current pathname. > > Unless you are talking about "2" line, saying "current" is somewhat > weird. I _think_ is the name in the index and in the working > tree, as opposed to the original path in the HEAD, but the > distinction does not matter for "1" or "U" lines. Right. The index path, since we only report renames for head-vs-index. > As this table is meant to be shared between "1" and "2", perhaps > > The pathname. In a renamed/copied entry, this > is the path in the index and in the working tree. > 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. > > or something like that may clarify it a bit better. Then in the > table for "U" lines, we can just say "The pathname". > >> + 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 original path. This is only present when the entry >> + has been renamed or copied. > > If it is explained as "the original path", wouldn't it be easier to > read if it were called "" instead of ""? yes. >> +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. > > Looks good. > > I think I saw "C-Quoted" elsewhere (perhaps in a in-code comment), > which should be spelled consistently i.e. "C-quoted". Right. Thanks, Jeff