Git::Nuggit::Status
This package will retrieve the status of a repository, including nested submodules. Functions are provided to display status, or the returned object can be used directly for processing.
This package is self-contained and does not depend on other Nuggit components. It utilizes Git porcelain=v2 syntax which requires Git 2.13.2+.
Typical usage:
chdir($top_level_proj_repo);
my $status = get_status({uno => 1}); # Get status, ignore tracked files
pretty_print_status($status);See "get_status"() below for details on output format.
STATE
The status value of each object is an enum-like value. The STATE() function can be used to translate between the integer and textual forms, for example STATE($status->{status}) may return 'modified', while STATE('modified') may return 4. The STATE() function is case-insensitive.
States are ordered in level of priority. The summary state of an object represents the greatest state of it, or any objects (submodules/files) beneath it.
Integer values of STATE enums may change in future revisions.
Supported states are: - clean - ignored - untracked - renamed - modified - conflict
get_status($opts)
Retrieve the status of a Git repository, and submodules.
The following options (in hash form) are currently supported:
get_status({ uno => 0, # If 1, pass '-uno' flag to ignore untracked files ignored => 0, # If 1, git may show any files that have been ignored (ie: due to a .gitignore) all => 1, # If 1, show all submodules, including those nominally un-modified. });
Output Format
Output is a nested object with the following keys for each:
- path - Path (or name) of this object - children - An array of known submodule names (those not in a 'clean' state) - objects - A hash of object definitions cataloged by their path (ie: file/submodule name). - status - Summary Status. This is the greatest state value (described above) of this object and its children - staged_status - Same as status, but in relation to changes staged for commit - staged_files_cnt - A count of modified files at this level and below, excluding submodule references. - unstaged_files_cnt - Same as staged_files_cnt, but for changes that have not been staged. - old_path - If an object was renamed, this will reflect t's old name - status_flag - Status (character) flag from Git for unstaged status. - staged_status_flag - Status (character) flag from Git for staged status. - is_submodule - Set to 1 if this object represents a submodule - sub_commit_delta - set to 1 if Git reports the commit tree has changed - sub_modified - set to 1 if there are tracked changes in this submodule - sub_untracked - Set to 1 if there are untracked files in this submodule - branch.ahead, branch.behind - If commit for a repository differs from upstream, how many commits ahead/behind - branch.oid - The current commit of this repository/submodule. - branch.head - The currently checked out branch - branch.* - Any additional 'header' information output by 'git --porcelain=v2 --branch' will be parsed. - branch_status_flag - True if any submodule is not on the same branch as it's parent. - detached_heads_flag - True if any submodule (or root) is in a detached HEAD state. =head3 Limitations
Branch information, including ahead-behind, detached state, or invalid branch is only calculated for submodules that are otherwise shown in the output. If a submodule does not have any outstanding changes, it will NOT be checked at this time. This is a limitation of git's porcelain status and will require an explicit query for additional submodules to resolve.
pretty_print_status($status_obj, $relative_path, $verbose)
Print repository status object to user, including additional summary details for the root level. It internally invokes do_pretty_print_status() to complete it's output.
See do_pretty_print_status() to output object information only for an object and it's children.
do_pretty_print_status($status, $relative_path, $root_path, $flags)
Output details on all objects in this $status object and it's children (submodules).
Parameters: - status - Status object from get_status(), or a nested object state - relativ_path - Relative path to repository root level. This will be concatenated with an object's path for display. If omitted, path will be relative to the top directory of the repository that the provided status object represents. - root_branch - If defined for applicable objects, output a warning if current branch does not match. - verbose - If set, always output additional information when known, for example commit hash.
show_status($status)
Similar to the STATE() function, converts a state (decimal value) to a user-friendly name, automatically colorizing selected states.
file_status($status_obj, $filename) Retrieve the status information for a given file or submodule from the overall status tree.
NOTICE: At present, $filename must be the full path to the file (or submodule) relative to the root repository. FUTURE ENHANCEMENTS: - Handle relative paths if given $relative_path_to_root - Handle regex/wildcard search for matching files. Option for negation pattern Ideally, detect if an input term is string or regex, and treat accordingly - Handle multiple input patterns
status_check($status)
Given a status object, return true only if there are no outstanding changes in working tree or stage, excluding untracked files but inclusive of submodule references.