diff options
author | Daniel Silverstone <dsilvers@digital-scurf.org> | 2015-07-17 13:57:11 +0100 |
---|---|---|
committer | Daniel Silverstone <dsilvers@digital-scurf.org> | 2015-07-17 13:57:11 +0100 |
commit | f5abb4368d85c4fcb8ceb65a668924a23cae2593 (patch) | |
tree | 242d7125150ca5c52c69d159a878258da612c3dd | |
parent | 5207d8bad1dbf29f72a08f9453bfb5bbf125acd4 (diff) | |
download | gall-f5abb4368d85c4fcb8ceb65a668924a23cae2593.tar.gz |
Add gall.ll documentation
-rw-r--r-- | lib/gall/ll.lua | 60 |
1 files changed, 60 insertions, 0 deletions
diff --git a/lib/gall/ll.lua b/lib/gall/ll.lua index 839669d..98b6858 100644 --- a/lib/gall/ll.lua +++ b/lib/gall/ll.lua @@ -9,6 +9,27 @@ --- -- Low level interface to Git -- +-- In addition to the documented functions below, the following Git subcommands +-- are directly exposed as functions which are essentially like... +-- +-- function gall.ll.FUNC(...) +-- return gall.ll.rungit("FUNC", ...) +-- end +-- +-- ...but with correct handling of the tabular input to @{rungit} +-- +-- The current full-list of those functions is: +-- +-- * cat_file exposes `git cat-file` +-- * symbolic_ref exposes `git symbolic-ref` +-- * show_ref exposes `git show-ref` +-- * hash_object exposes `git hash-object` +-- * ls_tree exposes `git ls-tree` +-- * init exposes `git init` +-- * merge_base exposes `git merge-base` +-- * rev_list exposes `git rev-list` +-- * config exposes `git config` +-- -- @module gall.ll @@ -30,6 +51,28 @@ local assert = assert local git_exe = "git" +--- +-- Run the given git process. +-- +-- The run parameters must contain: +-- +-- * The `repo` (the value for `GIT_DIR`) +-- * At least 1 list entry for the command line +-- * Optionally an `env` table. +-- * Optionally a string `stdin` to pass into the process +-- * Optionally a `stdout` boolean which says whether to capture stdout +-- * Optionally a `stderr` boolean which says whether to capture stderr +-- +-- Additionally, if `stdout` or `stderr` are functions instead of booleans then +-- they will be called to filter the stream after reading. +-- +-- @function rungit +-- @tparam table t Run parameters +-- @treturn number Exit code +-- @treturn string Contents of stdout +-- @treturn string Contents of stderr +-- @raise Function will assert if given no repository or if the subprocess is killed uncleanly + local function _rungit(t) assert(t.repo, "No repository?") @@ -82,6 +125,16 @@ local function _rungit(t) return why, stdout, stderr end +--- +-- Get / Set the git executable +-- +-- If `e` is provided, then it is set as the path, otherwise the current +-- path is returned as-is. By default, the Git executable is simply `git`. +-- +-- @function get_set_git +-- @tparam ?string e The path to the Git executable +-- @treturn string The path to the Git executable + local function get_set_git(e) if e then git_exe = e @@ -89,6 +142,13 @@ local function get_set_git(e) return git_exe end +--- +-- Remove a trailing newline if present. +-- +-- @function chomp +-- @tparam string s The string to chomp +-- @treturn string `s` with a single trailing newline (if present) removed. + local function _chomp(s) local rest = s:match("^(.*)\n$") return rest or s |