SYNOPSIS

ngt stash [options] <cmd>

Nuggit stash performs a submodule-aware 'stash' operation across all submodules. If there are any changes to be stashed, it will create a new entry in .nuggit/stashes and generate a uniquely named stash in each submodule. This ensures consistent ngt stash save/pop behavior.

Usgae is largely equivalent to git stash. Note that, to avoid conflicts with any stash operations performed outside of this tool, Nuggit will mark all messaaes with "NGT-STASH{idx}" which can be seen if running "git stash list".

Common usage is: - ngt stash push Save all current changes in the stash - ngt stash pop Pop the last stash created with nuggit - ngt stash list List all stashes previously saved with nuggit. - ngt stash apply $idx Apply the specified stash index. Note: Unlike git stash, only the number needs to be specified. - ngt stash --man Show the full documentation

General Options

The following optins are valid for all stash subcommands;

--help

Display an abbreviated help menu

--man

Display detailed documentation.

--verbose

Display additional details.

Stash Commands

Note: The majority of the commands below are verbatim copies of the underlying git commands, with the descriptions para-phrased from the official Git man pages.

push

ngt stash save [<pathspec>]

This command saves all uncommitted changes to the stash. If pathspec is specified, it will be used to filter which files and/or submodules are stashed. The following options are supported.

--patch | -p

Prompt the user to interactively select hunks from the diff between HEAD and the working tree to be stashed.

--keep-index | -k

If specified, do not stage any changes already in the index (staged).

--include-untracked | u

All untracked files are also stashed and then cleaned up with git clean .

--all | -a

All ignored and untracked files are also stashed and then cleaned up with git clean.

-m | --message <message>

Specify a description for this stash.

list

Display a listing of all stashes known to nuggit.

NOTE: Nuggit maintains it's own listing of nuggits and will not display any stashes created manually with git, nor will it detect if stashes have been cleared outside of nuggit.

pop

Apply the last stash entry in the list. If the operation completes without error, it will automatically be dropped.

apply

Equivalent to pop, except that the entry will not be dropped from the stash listing (internally to Nuggit, or to git).

drop

Internal Configuration Format

Nuggit stash configuration is saved to .nuggit/stash in a JSON file containing an object as described below.

Note: This is NOT considered a user configuration file and the format may change in future releases.

- Version. An integer version number for the nuggt stash configuration version intended to facilitate future updates. - list - An array of known stashes. Each entry is an object containing - name (optional) - idx - Internal index number for automatic naming. Index numbers will never be reused. - timestamp - Timestamp stash was created - root_commit - SHA of root module commit at time of creation - root_timestamp - Timestamp of root module commit at time of creation (included here for reference) - branch - The branch checked out in the root module at the time of creation

TODO

- stash show command (with optional patches) - stash delete command - Retrive stash by custom name? - branch command - Verify editor prompts will pass through in patch mode, even when using ngt->run - For disambiguation, support for '--' to seperate arguments, in this case paths - Stash naming convention - Stash behvior if run in a folder without any changes to stash (return code, stdout/stderr output) - Option for specifying a specific set of files or submodules to stash (or to exclude), and/or to add submodule to existing stash set

- Future: Ability to stash changes to submodule references (ie: perform checkout of original reference commit for submodules, when content of submodule is otherwise unmodified)