evhan  committed de84c51

Document some previously undocumented procedures

  • Participants
  • Parent commits d80fdb8

Comments (0)

Files changed (2)

 (: branches-fold (forall (a b) ((branch a -> b) a repository #!optional symbol -> (or a b))))
 (: create-branch (repository #!rest -> branch))
-(define (branch repo name #!optional (type 'all))
+(define (branch repo name #!optional (type 'local))
   (pointer->reference repo (git-branch-lookup (repository->pointer repo) name type)))
 ;; I'm changing branch-move to branch-rename here, perhaps gratuitously.
 <procedure>(repository-head-orphan? repositoy) => boolean</procedure>
 <procedure>(repository-head-detached? repositoy) => boolean</procedure>
+<procedure>(repository-head-unborn? repositoy) => boolean</procedure>
 Returns a boolean indicating whether the given repository's {{HEAD}} (a
-symbolic reference) is orphaned (unreferenced under the refs namespace)
-or detached (refering to a commit rather than a branch).
+symbolic reference) is orphaned (unreferenced under the refs namespace),
+detached (refering to a commit rather than a branch), or has yet to be
+created, respectively.
 ==== OID
 On success, the on-disk repository is updated immediately.
+<procedure>(branch repository name [type]) => (or reference false)</procedure>
+Retrieves a {{reference}} to the branch of the given {{name}} from the
+repository. {{name}} should be a string naming a branch without a
+leading reference namespace such as "refs/heads/" or "refs/remotes". An
+error is signaled if no such branch exists.
+A {{type}} symbol may be given, either {{local}} or {{remote}}, to
+specify what type of branch should be looked up; by default, {{local}}
+is used.
 <procedure>(branches-fold kons knil repository [type]) => object</procedure>
 Folds over the given {{repository}}'s branches.
 {{all}}, to specify what type of branches should be listed; by default,
 {{all}} is used.
-<procedure>(branches repository [type]) => (list-of branch)</procedure>
+<procedure>(branches repository [type]) => (list-of reference)</procedure>
 Returns a list {{reference}} objects for each branch in the given
 {{repository}}. A type symbol may be given to filter the branches, as in
 {{branches-fold}}. The order of the resulting list is unspecified.
+<procedure>(branch-head? reference) => boolean</procedure>
+Determines whether the given branch {{reference}} is its repository's
+current {{HEAD}}.
 <procedure>(branch-name reference) => string</procedure>
 Returns the name of the given branch {{reference}}. This is similar to
 ==== Generic Procedures
 These procedures can be used on any objects of the four main Git object
-types: {{commit}}, {{tree}}, {{tag}} and {{blob*}}.
+types: {{commit}}, {{tree}}, {{tag}} and {{blob}}.
 <procedure>(object-id object) => oid</procedure>
 Returns the full commit message or message encoding for the given
+<procedure>(commit-header commit) => string</procedure>
+Returns a string header for the given {{commit}}, which is a textual
+display of its author, committer, tree and parent commit.
 <procedure>(commit-tree commit) => tree</procedure>
 <procedure>(commit-tree-id commit) => oid</procedure>
 <procedure>(commit-parentcount commit) => int</procedure>
 <procedure>(commit-parent commit [n]) => (or commit false)</procedure>
+<procedure>(commit-parent-id commit [n]) => (or oid false)</procedure>
 <procedure>(commit-parents commit) => (list-of commit)</procedure>
 <procedure>(commit-ancestor commit [n]) => (or commit false)</procedure>
 the first parent if no {{n}} is given. If the {{commit}} has no parent,
 {{#f}} is returned.
+{{commit-parent-id}} is as {{commit-parent}}, but it returns the {{oid}}
+of the given {{commit}}'s parent without first reading the parent commit
+from the repository.
 {{commit-parents}} returns the possibly-empty list of all parents of the
 given {{commit}}. The order of this list is unspecified.
 modifying the on-disk repository on success. The resulting {{tree}} is
+<procedure>(tree-builder-clear tree-builder) => void</procedure>
+Removes all objects from the given {{tree-builder}}.
 ==== Diff