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).