`git`: functions module for shellfire

This module provides a simple set of wrapper functions for making it more pleasant to work with git.

Compatibility

Current HEAD is compatible with shellfire release release_2015.0117.1750-1.

Overview

Usage couldn't be simpler. Just pick a function. Please note that most functions are not currently documented.

Importing

To import this module, add a git submodule to your repository. From the root of your git repository in the terminal, type:-

mkdir -p lib/shellfire
cd lib/shellfire
git submodule add "https://github.com/shellfire-dev/git.git"
cd -
git submodule init --update

You may need to change the url https://github.com/shellfire-dev/git.git above if using a fork.

You will also need to add paths - include the module paths.d.

Namespace `git`

This namespace contains useful functions wrapping git.

To use in code

If calling from another shellfire module, add to your shell code the line

core_usesIn git

in the global scope (ie outside of any functions). A good convention is to put it above any function that depends on functions in this module. If using it directly in a program, put this line inside the _program() function:-

_program()
{
	core_usesIn git
	…
}

Functions

`git_mostRecentCommit()`

Parameter	Value	Optional
`gitRepositoryPath`	Path to a git repository (or submodule), ie a path with a `.git` folder or file.	No

The function prints to standard out, without a trailing new line, the most recent commit hash (a full hash is returned, eg 166bcda6abd46e7e1f0107ad4006323a9398afd3). A typical usage might be:-

lastCommit="$(git_mostRecentCommit "/path/to/repo/folder")"

Does not check the path exists.

`git_commitToTagOrCommit`

Parameter	Value	Optional
`gitRepositoryPath`	Path to a git repository (or submodule), ie a path with a `.git` folder or file.	No
`commit`	A commit hash (eg retrieved with `git_mostRecentCommit()`).	No

The function prints to standard out, without a trailing new line, the tag that that exaxtly matches the commit hash, or, if not present, returns commit. A typical usage might be:-

tagOrCommit="$(git_commitToTagOrCommit "/path/to/repo/folder" "166bcda6abd46e7e1f0107ad4006323a9398afd3")"

`git_withOutputSilencedIfQuiet()`

Parameter	Value	Optional
`verbosityLevel`	A number such as `1`, `2`, etc that matches `--verbosity` on the command line.	No
`gitCommand`	Git command, eg `clean`	No
`gitCommandArguments`	Zero or more arguments to pass to `gitCommand`	Yes

Helper function to only make git commands noisy if a verbosity threshold is met or exceeded. Runs gitComand [gitCommandArguments] if verbosityLevel is matched or exceeded, otherwise runs gitComand -q [gitCommandArguments]. gitCommand must be able to accept -q (not all commands do).

shellfire-dev/git

git: functions module for shellfire