Documentation
¶
Overview ¶
Package statusv1 parses the output of `git status --porcelain=v1`.
This package provides parsing for Git's machine-readable status format, supporting both regular line-terminated output and NUL-terminated output (with -z flag). This package implements parsing of the original porcelain=v1 format, which is simpler than the more modern porcelain=v2 format.
Basic Usage ¶
Parse takes an io.Reader containing `git status --porcelain=v1` output.
r := bytes.NewReader(gitStatusOutput)
status, err := statusv1.Parse(r)
if err != nil {
log.Fatal(err)
}
ParseZ provides a variant that will work with NUL-terminated git status output (from -z flag).
Working with Results ¶
The Status struct contains parsed information, notably the list of file entries, which can be accessed via the [Status.Entries] field. Each entry is represented by an Entry struct, which contains the XY status flags and file paths.
Git Status Format ¶
This package parses Git's porcelain=v1 format, which provides machine-readable output with basic information about file status and branch state. The format is stable across Git versions and designed for programmatic consumption.
The porcelain=v1 format outputs one line per file:
XY PATH XY ORIG_PATH -> PATH (for renames/copies)
Where XY is a two-character status code indicating the state of the file in the index (X) and working tree (Y).
There is also an alternate -z format recommended for machine parsing. In that format, the status field is the same, but some other things change. First, the -> is omitted from rename entries and the field order is reversed (e.g from -> to becomes to from). Second, a NUL (ASCII 0) follows each filename, replacing space as a field separator and the terminating newline (but a space still separates the status field from the first filename). Third, filenames containing special characters are not specially formatted; no quoting or backslash-escaping is performed.
In most cases, users should prefer the more modern porcelain=v2 format, which provides more detailed information and additional features. See the [statusv2] package for parsing porcelain=v2 output.
For more information about the porcelain=v1 format, see the Git documentation for git status.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Entry ¶
type Entry struct {
XY XYFlag // two-character status code
Path string // current path of the file
OrigPath string `json:",omitempty"` // original path for renamed/copied files (empty if not renamed/copied)
}
Entry represents a single file entry in git status --porcelain=v1 output.
type State ¶
type State byte
State represents a single character from Git porcelain=v1 status codes.
const ( Unmodified State = ' ' // unmodified (no changes) Modified State = 'M' // modified TypeChanged State = 'T' // file type changed (regular file, symbolic link or submodule) Added State = 'A' // added Deleted State = 'D' // deleted Renamed State = 'R' // renamed Copied State = 'C' // copied (if status.renames=copies) UpdatedUnmerged State = 'U' // updated but unmerged (merge conflict) Untracked State = '?' // untracked files Ignored State = '!' // ignored files )
Git status state codes for index (X) and worktree (Y) changes.
The Unmodified state is represented by a space (' ') in porcelain=v1, which is different from the '.' used in porcelain=v2.
In porcelain=v1, the XYFlag is used represent untracked ('?') and ignored ('!') files, but in porcelain=v2, these become separate entry types.
type Status ¶
type Status struct {
Headers []string // header lines (prefixed with `##`), if present
Entries []Entry // file entries
}
Status represents the parsed output of git status --porcelain=v1.
The Header field contains any header lines from the output, which may be present when using flags such as --branch. These lines are always prefixed with `##`.
func Parse ¶
Parse parses git status --porcelain=v1 output from an io.Reader.
Headers: When using --branch in conjunction with git status --porcelain=v1, the output may contain header lines, for example, `## main...origin/main [ahead 1]`. These lines are preserved with ordering intact in the Headers field of the returned Status struct, but are not parsed as they are not documented as part of the --porcelain=v1 format.
Path Handling: Paths containing special characters may be quoted by Git according to core.quotePath configuration. This function preserves paths exactly as provided by Git without unquoting. If your application needs unquoted paths, consider using ParseZ with the -z flag instead, as Git does not quote paths in -z format.
func ParseZ ¶
ParseZ parses git status --porcelain=v1 -z output from an io.Reader.
In the -z format, entries are terminated by NUL bytes instead of newlines, and rename entries have the format "XY to\x00from\x00" instead of "XY from -> to".
Headers: When using --branch in conjunction with git status --porcelain=v1, the output may contain header lines, for example, `## main...origin/main [ahead 1]`. These lines are preserved with ordering intact in the Headers field of the returned Status struct, but are not parsed as they are not documented as part of the --porcelain=v1 format.
Path Handling: In -z format, Git does not quote paths containing special characters, so all paths are provided as-is. This function preserves paths exactly as provided by Git.
type XYFlag ¶
XYFlag represents the two-character status code in porcelain=v1 format. The X position shows the status of the index, and the Y position shows the status of the working tree.
func (XYFlag) MarshalText ¶
MarshalText implements encoding.TextMarshaler for XYFlag.
func (*XYFlag) UnmarshalText ¶
UnmarshalText implements encoding.TextUnmarshaler for XYFlag.
Source Files