diff options
author | Daniel Silverstone <dsilvers@digital-scurf.org> | 2015-07-16 16:56:37 +0100 |
---|---|---|
committer | Daniel Silverstone <dsilvers@digital-scurf.org> | 2015-07-16 16:56:37 +0100 |
commit | 2ef4f446f91fc731d990ee7609b2bd365347be43 (patch) | |
tree | 64a0c1f0c3b48850253bcfed9f04f9484994af7f | |
parent | 70f08889dea615f41081e4a9b3adc302240cd0c4 (diff) | |
download | gall-2ef4f446f91fc731d990ee7609b2bd365347be43.tar.gz |
Basic documentation for the commit object
-rw-r--r-- | lib/gall/commit.lua | 101 |
1 files changed, 101 insertions, 0 deletions
diff --git a/lib/gall/commit.lua b/lib/gall/commit.lua index bd6f341..ce1d375 100644 --- a/lib/gall/commit.lua +++ b/lib/gall/commit.lua @@ -19,6 +19,35 @@ local parsed = setmetatable({}, {__mode="k"}) local _new +--- +-- Who, when +-- +-- Encapsulation of git's author/committer who and when data +-- +-- @type whowhen + +--- +-- The "real" name of the person. +-- +-- @field realname + +--- +-- The email address of the person. +-- +-- @field email + +--- +-- The UNIX time (seconds since epoch) for the signature line +-- +-- @field unixtime + +--- +-- The timezone in which the signature took place (+/-HHHH) +-- +-- @field timezone + +--- @section end + local function parse_person(pers) local real, email, when, tz = pers:match("^(.-) <([^>]+)> ([0-9]+) ([+-][0-9]+)$") return { @@ -97,11 +126,62 @@ local function committostring(commit) return "<GitCommit(" .. tostring(objs[commit].sha) .. ") in " .. tostring(repos[commit]) .. ">" end +--- +-- Commit object. +-- +-- @type commit + +--- +-- The tree object referenced by this commit. +-- +-- @field tree +-- @see gall.tree + +--- +-- The author of the commit as a @{whowhen} object +-- +-- @field author + +--- +-- The committer of the commit as a @{whowhen} object +-- +-- @field committer + +--- +-- The parents of the commit (zero or more @{commit} objects) +-- +-- @field parents + +--- +-- The commit message +-- +-- @field message + +--- +-- The signature on the commit (if present) +-- +-- @field signature + +--- +-- The SHA1 OID of the commit +-- +-- @field sha + +--- @section end + local commitmeta = { __index = commitindex, __tostring = committostring } +--- +-- Instantiate a new @{commit} object for the given raw git object +-- +-- @function new +-- @tparam repository repo The repository containing the commit +-- @tparam object obj The raw git object for the commit +-- @treturn commit The new commit instance + local function _new(repo, obj) local ret = setmetatable({}, commitmeta) objs[ret] = obj @@ -109,6 +189,27 @@ local function _new(repo, obj) return ret end +--- +-- Create a new commit object in the repository. +-- +-- The given data must contain all of: +-- +-- * tree - The tree object for the commit +-- * author - The author (as a table of realname and email) +-- * committer - The committer (as a table of realname and email) +-- * message - The commit message +-- +-- It may optionally contain: +-- +-- * parents - The list of parent commit objects. +-- +-- @function create +-- @tparam repository repo The repository to create the commit in +-- @tparam table data The commit data +-- @treturn[1] commit The newly added commit object +-- @treturn[2] nil Nil on error +-- @treturn[2] string The error message + local function _create(repo, data) if not data.tree then return nil, "No tree?" |