Nuggit Library

This library provides common utility functions for interacting with repositories using Nuggit.

Procedural Methods

get_submodules()

Return an array of all submodules from current (or specified) directory and below listed depth-first, queried via git submodule foreach.

NOTE: Direct usage of submodule_foreach() is preferred when possible.

list_submodules_here([path])

Return an array listing all submodules of the current (or specified) directory. This function uses 'git config' to parse the .gitmodules file and is NOT recursive.

submodule_foreach(fn)

WARNING: This function is now deprecated in favor of $ngt->foreach and will be phased out in a future release.

Recurse into each submodule and execute the given command. This is roughly equivalent to "git submodule foreach"

Parameters:

fn

Callback function to be called foreach submodule found. CWD will be at root of current submodule.

Callback will always be called starting from the deepest submodule.

Function will be called with

-parent Relative path from root to parent -name Name of submodule. $name/$parent is full path from root -status If modified, '+' or '-' as reported by Git -hash Commit SHA1 -label Matching Branch/Tag as reported by Git (?)

parent Relative path from root to parent

name Name of submodule. $name/$parent is full path from root

status If modified, '+' or '-' as reported by Git

hash Commit SHA1

label Matching Branch/Tag as reported by Git (?)

opts

Hash containing list of user options. Currently supported options are:

recursive If false, do not recurse into nested submodules

breadth_first_fn If defined, execute this callback function prior to recursing into nested submodules.

The main callback function is executed after visiting all nested submodules.

recursive

If set, or undefined, recurse into any nested submodules. If set to 0, only visit submodules of the current repository.

TODO/FUTURE: parallel

If defined, parse each submodule in parallel using fork/wait

FUTURE: Option may include a check if .gitmodules matches list reported by git submodule

parent

Path of Parent Directory. In each recursion, the submodule name will be appended.

find_root_dir

Returns the root directory of the nuggit, or undef if not found Also navigate to the nuggit root directory

nuggit_init

Initialize Nuggit Repository by creating a .nuggit file at current location.

get_remote_tracking_branch

Get the name of the default branch used for pushes/pulls for this repository.

NOTE: This function may serve as the basis for an improved get_selected_branch() function that retrieves additional information.

get_selected_branch_here

?

get_selected_branch

 get the checked out branch from the list of branches
 The input is the output of git branch (list of branches)

get_branches

Get a listing of all branches in the current repository/directory.

Supported options (passed directly to git) include: - get_branches() - Return a list of all local branches - get_branches("-a") - Return a list of all local+remote branches (ie: $branch or remotes/origin/$branch) - get_branches("-r") - Return a list of all remote branches (ie: origin/$branch) - get_branches("--merged") - get_branches("--no-merged")

Returns a hash where key is branch name and value will be a hash with any known details.

do_upcurse

Find the top-level of this project and chdir into it. If not a nuggit project, 'die'

Returns root_dir since this is often needed by callers. (FUTURE: This should be an OOP method, in which case this return value would be deprecated in favor of class variable)

check_merge_conflict_state()

Checks if a merge operation is in progress, and dies if it is.

This function should be called with the path to the nuggit root repository or with that as the current working directory.

DEPRECATED - Use $ngt->merge_conflict_state(1) instead

Object Oriented Interface

The following is an initial cut at an OOP interface. The OOP interface is incomplete at this stage and serves primarily as a convenience wrapper for other commands, and Nuggit::Log

run_foreach

Run given command (str) in the current repository, and all nested submodules.

Note: Current repository corresponds to current working directory. To run from nuggit root, user should change directories first. This permits greater flexibility in usage.

run

Execute the given git command from the current directory. The command will be wrapped in IPC::Run3 in order to capture stdout, stderr, and exit status. Output and 'die' functionality are controlled by object settings.

Usage: my ($status, $stdout, $stderr) = run($cmd [,@args]);

TODO: @args to be added later, for now a single string expected TODO: Optional parameters to overrride object default for die_on_error and run_echo_always.

merge_conflict_state()

If no argument is specified, it returns true if a merge operation is in progress, false otherwise.

If any parameter is defined, then we will die with an appropriate error if a merge is in progress.

foreach(opts)

Recurse into each submodule and execute the given command. This is roughly equivalent to "git submodule foreach" with added functionality.

It accepts a hashref as it's sole parameter which may contain the following fields. Parameters:

breadth_first

Callback function to be called foreach submodule with breadth-first recursion (starting from the top level). CWD will be at root of current submodule. See below for arguments provided.

depth_first

Callback function to be called foreach submodule with depth-first recursion (starting from most nested). CWDW will be at roto of current submodule. See below for arguments provided.

recursive If false, do not recurse into nested submodules

run_root If true, execute defined callbacks on the root repository as well.

modified_only If true, execute and recurse into submodules that Git reports as modified, uninitialized, o rin a conflicted state only.

parallel. Reserved for future parallel processing enhancements.

Callback functions will be called with a single hashref argument containing the following fields

opts - A copy of the input options parent - The name of the parent repository name - The name of this submodule

The above fields will be defined for the root repository (if run_root) and all submodules, while the following fields only apply to submodules:

status - The status for this repository. 0 for unmodified, '+' for modified, '-' for uninitialized, 'U' for pending merge conflicts.

cpanm Git::Nuggit

perl -MCPAN -e shell
install Git::Nuggit