Basic repository documentation

1 files changed, 190 insertions, 11 deletions

diff --git a/lib/gall/repository.lua b/lib/gall/repository.lua
index f5dac66..57031ba 100644
--- a/lib/gall/repository.lua
+++ b/lib/gall/repository.lua
@@ -35,6 +35,15 @@ local function _repotostring(repo)
    return "<GitRepository(" .. repo.path .. ")>"
 end
 
+---
+-- Abstracted representation of a Git repository.
+--
+-- A repository instance represents a Git repository on disk.  It is the
+-- interface through which all interaction with a Git repository begins.
+--
+-- @type repository
+
+
 function repomethod:_run_with_input_and_env(env, input, want_output, ...)
    local t = {...}
    t.repo = self.path
@@ -60,19 +69,66 @@ function repomethod:_run(want_output, ...)
    return self:_run_with_input(nil, want_output, ...)
 end
 
+---
+-- Run a git command across a repository and gather its stdout
+--
+-- This will run the supplied git command within the repository and will
+-- return the stdout of the run, with the final newline removed.
+--
+-- For return values, see @{gall.ll.rungit}
+--
+-- @function gather
+-- @tparam string command The git command name
+-- @tparam string ... The arguments to the git command
+-- @treturn ... As per @{gall.ll.rungit}
+-- @see gall.ll.rungit
+-- @see repository:rawgather
+
 function repomethod:gather(...)
    return self:_run(chomp, ...)
 end
 
+---
+-- Run a git command across a repository and gather its stdout raw.
+--
+-- This will run the supplied git command within the repository and will
+-- return the stdout of the run without processing it at all.
+--
+-- For return values, see @{gall.ll.rungit}
+--
+-- @function rawgather
+-- @tparam string command The git command name
+-- @tparam string ... The arguments to the git command
+-- @treturn ... As per @{gall.ll.rungit}
+-- @see gall.ll.rungit
+-- @see repository:gather
+
 function repomethod:rawgather(...)
    return self:_run(true, ...)
 end
 
+---
+-- Force the empty tree object to exist and return it.
+--
+-- @function force_empty_tree
+-- @treturn object The git object representing the empty tree
+
 function repomethod:force_empty_tree()
    self:_run(true, "hash-object", "-t", "tree", "-w", "/dev/null")
    return self:get(tree.empty_sha)
 end
 
+---
+-- Calculate the hash of the given object, optionally injecting it into
+-- the repository store.
+--
+-- @function hash_object
+-- @tparam string type The type of the object
+-- @tparam string content The raw content of the object
+-- @tparam boolean inject Whether or not to inject the object into the store.
+-- @treturn[1] string The OID of the given object
+-- @treturn[2] nil Nil on error.
+
 function repomethod:hash_object(type, content, inject)
    local args = {
       "hash-object", "-t", type, "--stdin",
@@ -84,6 +140,14 @@ function repomethod:hash_object(type, content, inject)
    return (ok == 0) and sha or nil
 end
 
+---
+-- Get the OID referent of the given reference.
+--
+-- @function get_ref
+-- @tparam string ref The reference name
+-- @treturn[1] string The OID referent
+-- @treturn[2] nil Nil on error
+
 function repomethod:get_ref(ref)
    local ok, sha = self:_run(chomp, "show-ref", "--verify", "-s", ref)
    return (ok == 0) and sha or nil
@@ -95,6 +159,19 @@ if ll.git2 then
    end
 end
 
+---
+-- Update the given reference.
+--
+-- If new_ref is nil then the reference is to be deleted.
+-- If reason is nil, then `"Gall internal operations"` will be used.
+-- If old_ref is nil then the reference must not exist before calling this.
+--
+-- @function update_ref
+-- @tparam string ref The reference to update
+-- @tparam ?string new_ref The OID to update the reference to point at
+-- @tparam ?string reason The reason for updating the reference (for reflog)
+-- @tparam ?string old_ref The old OID (for preventing race conditions)
+
 function repomethod:update_ref(ref, new_ref, reason, old_ref)
    if new_ref and not old_ref then
       old_ref = string.rep("0", 40)
@@ -125,6 +202,16 @@ function repomethod:update_ref(ref, new_ref, reason, old_ref)
    return true
 end
 
+---
+-- Ensure the HTTP server info is updated in the repository.
+--
+-- This essentially just calls `git update-server-info`
+--
+-- @function update_server_info
+-- @treturn[1] boolean True on success
+-- @treturn[2] nil Nil on error
+-- @treturn[2] string The error message
+
 function repomethod:update_server_info()
    local why = self:_run(false, "update-server-info")
    if why ~= 0 then
@@ -133,6 +220,16 @@ function repomethod:update_server_info()
    return true
 end
 
+---
+-- Return all (non-symbolic) references in the repository.
+--
+-- The returned table is a map from reference name to the SHA1 referent.
+--
+-- @function all_refs
+-- @treturn[1] table The references in the repository
+-- @treturn[2] nil Nil on error
+-- @treturn[2] string The error message
+
 function repomethod:all_refs()
    local ok, refs = self:_run(chomp, "show-ref")
    if ok ~= 0 then return nil, refs end
@@ -143,6 +240,15 @@ function repomethod:all_refs()
    return reft
 end
 
+---
+-- Normalise a given _SHAish_ to a true OID.
+--
+-- @function normalise
+-- @tparam string sha The _SHAish_ to normalise.
+-- @treturn[1] string The full OID referred to by _SHAish_
+-- @treturn[2] nil Nil on error
+-- @treturn[2] string The error message.
+
 function repomethod:normalise(sha)
    -- Purpose is to take a 'shaish' object and normalise it
    if sha:match(pattern.fullsha) then
@@ -172,6 +278,15 @@ function repomethod:normalise(sha)
    return nil, "Unable to normalise " .. tostring(sha)
 end
 
+---
+-- Retrieve an object from the repository.
+--
+-- @function get
+-- @tparam string _sha The _SHAish_ to retrieve.
+-- @treturn[1] object The low level object representing the given _SHAish_.
+-- @treturn[2] nil Nil on error
+-- @treturn[2] string The error message
+
 function repomethod:get(_sha)
    local sha, err = self:normalise(_sha)
    if not sha then
@@ -185,6 +300,18 @@ function repomethod:get(_sha)
    return ret
 end
 
+---
+-- Calculate the merge base(s) for the given sha pair
+--
+-- @function merge_base
+-- @tparam string sha_1 The left-side OID for the merge
+-- @tparam string sha_2 The right-side OID for the merge
+-- @tparam boolean get_all Whether to retrieve all possible merge bases.
+-- @treturn[1] boolean True if there simply isn't a merge base to be found
+-- @treturn[2] string... The OID(s) of the merge base(s)
+-- @treturn[3] nil Nil on error
+-- @treturn[3] string The error message
+
 function repomethod:merge_base(sha_1, sha_2, get_all)
    local args = { sha_1, sha_2 }
    if get_all then
@@ -235,6 +362,18 @@ if ll.git2 then
    end
 end
 
+---
+-- Calculate the revision list shared between the given tips.
+--
+-- @function rev_list
+-- @tparam string oldhead The "old" tip of the commit tree.
+-- @tparam string newhead The "new" tip of the commit tree.
+-- @tparam boolean firstonly Whether to return only the first shared revision
+-- @treturn[1] boolean True if there are no shared commits
+-- @treturn[2] string... The OIDs of the shared revision(s)
+-- @treturn[3] nil Nil on error
+-- @treturn[3] string The error message
+
 function repomethod:rev_list(oldhead, newhead, firstonly)
    local args = { newhead, "^" .. oldhead }
    if firstonly then
@@ -256,6 +395,18 @@ function repomethod:rev_list(oldhead, newhead, firstonly)
    return ret
 end
 
+---
+-- Get or set the given symbolic reference.
+--
+-- @function symbolic_ref
+-- @tparam string name The reference to get or set
+-- @tparam[opt] string toref The referent for the symbolic reference.
+-- @treturn[1] boolean False if the reference queried and was not found
+-- @treturn[2] boolean True if the reference was queried and found (or set)
+-- @treturn[2] string The referent of the given reference.
+-- @treturn[3] nil Nil on error
+-- @treturn[4] string The error message
+
 function repomethod:symbolic_ref(name, toref)
    if toref then
       local ok, ref, err = ll.symbolic_ref { "-q", name, toref,
@@ -291,6 +442,16 @@ if ll.git2 then
    end
 end
 
+---
+-- Interact with the git configuration.
+--
+-- @function config
+-- @tparam string confname The name of the configuration value to query/set
+-- @tparam[opt] value The value to set (or nil to query the current value)
+-- @treturn[1] string The value of the configuration entry if queried
+-- @treturn[2] nil Nil on error
+-- @treturn[2] string The error message
+
 function repomethod:config(confname, value)
    -- Trivial interface to key/value in config
    if not value then
@@ -329,6 +490,22 @@ local repomt = {
    __tostring = _repotostring
 }
 
+
+--- @section end
+
+---
+-- Create a new repository object for a given git repository.
+--
+-- Create a new @{repository} object representing the given git repository.
+-- If the path refers to a repository with a working tree (non-bare) then
+-- the `/.git` is automatically added.
+--
+-- @function new
+-- @tparam string path The path to the repository to open.
+-- @treturn[1] repository The newly created repository.
+-- @treturn[2] nil Nil on error.
+-- @treturn[2] string The error message.
+
 local function _new(path)
    -- return a new git repository object
    -- with the git_dir set for the provided path
@@ -366,20 +543,22 @@ local function _new(path)
    retrepo.work = workpath
    retrepo.HEAD = symref
 
---[[
--- This seems redundant
-   if ll.git2 then
-      local git2, msg = ll.git2.Repository(retrepo.path)
-      if not git2 then
-	 return nil, msg
-      end
-      local odb = git2:odb()
-      retrepo.git2 = { repo = git2, odb = odb }
-   end
---]]
    return setmetatable(retrepo, repomt)
 end
 
+
+---
+-- Create a repository
+--
+-- Create a new repository on disk and return its representation.
+--
+-- @function create
+-- @tparam string path The path to the repository to be created.
+-- @tparam boolean full Whether to create a full repository or a bare one.
+-- @treturn[1] repository The newly created repository
+-- @treturn[2] nil Nil on error
+-- @treturn[2] string The error message
+
 local function _create(path, full)
    -- Cause a bare repository to be created (or a non-bare if full is true)
    local args = { stderr = true, repo = path, "-q" }