document the current public API
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302
diff --git a/include/got_diff.h b/include/got_diff.h
index f7ac2b2..4673b9c 100644
--- a/include/got_diff.h
+++ b/include/got_diff.h
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2017 Stefan Sperling <stsp@openbsd.org>
+ * Copyright (c) 2018 Stefan Sperling <stsp@openbsd.org>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
@@ -14,7 +14,18 @@
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
+/*
+ * Compute the differences between two blobs and write unified diff text
+ * to the provided output FILE. Two const char * diff header labels may
+ * be provided which will be used to identify each blob in the diff output.
+ * If a label is NULL, use the blob's SHA1 checksum instead.
+ */
const struct got_error *got_diff_blob(struct got_blob_object *,
struct got_blob_object *, const char *, const char *, FILE *);
+
+/*
+ * Compute the differences between two trees and write unified diff text
+ * to the provided output FILE.
+ */
const struct got_error *got_diff_tree(struct got_tree_object *,
struct got_tree_object *, struct got_repository *, FILE *);
diff --git a/include/got_error.h b/include/got_error.h
index ad4669b..4927b60 100644
--- a/include/got_error.h
+++ b/include/got_error.h
@@ -80,6 +80,21 @@ static const struct got_error {
{ GOT_ERR_WORKTREE_BUSY,"worktree already locked" },
};
-const struct got_error * got_error(int code);
+/*
+ * Get an error object from the above list, for a given error code.
+ * The error message is fixed.
+ */
+const struct got_error *got_error(int);
+
+/*
+ * Get a statically allocated error object with code GOT_ERR_ERRNO
+ * and an error message obtained from strerror(3).
+ */
const struct got_error *got_error_from_errno(void);
+
+/*
+ * If ferror(3) indicates an error status for the FILE, obtain an error
+ * from got_error_from_errno(). Else, obtain the error via got_error()
+ * with the error code provided in the second argument.
+ */
const struct got_error *got_ferror(FILE *, int);
diff --git a/include/got_object.h b/include/got_object.h
index 2b3af38..335f73e 100644
--- a/include/got_object.h
+++ b/include/got_object.h
@@ -44,6 +44,7 @@ struct got_commit_object {
char *logmsg;
};
+/* A generic object. Used as a handle which holds an ID and an object type. */
struct got_object;
#define GOT_OBJ_TYPE_COMMIT 1
#define GOT_OBJ_TYPE_TREE 2
@@ -55,27 +56,115 @@ struct got_object;
struct got_repository;
+/*
+ * Obtain a string representation of an object ID. The output depends on
+ * the hash function used by the repository format (currently SHA1).
+ */
const struct got_error *got_object_id_str(char **, struct got_object_id *);
+
+/*
+ * Compare two object IDs. Return value behaves like memcmp(3).
+ */
int got_object_id_cmp(struct got_object_id *, struct got_object_id *);
+
+/*
+ * Created a newly allocated copy of an object ID.
+ * The caller should dispose of it with free(3).
+ */
struct got_object_id *got_object_id_dup(struct got_object_id *);
+
+/*
+ * Get a newly allocated copy of an object's ID.
+ * The caller should dispose of it with free(3).
+ */
struct got_object_id *got_object_get_id(struct got_object *);
+
+/*
+ * Obtain the type of an object.
+ * Returns one of the GOT_OBJ_TYPE_x values (see above).
+ */
int got_object_get_type(struct got_object *);
+
+/*
+ * Attempt to open the object in a repository with the provided ID.
+ * Caller must dispose of it with got_object_close().
+ */
const struct got_error *got_object_open(struct got_object **,
struct got_repository *, struct got_object_id *);
+
+/*
+ * Attempt to map the provided ID string to an object ID and then
+ * attempt to open the object in a repository with this ID.
+ * The form of an ID string depends on the hash function used by the
+ * repository format (currently SHA1).
+ * Caller must dispose of the object with got_object_close().
+ */
const struct got_error *got_object_open_by_id_str(struct got_object **,
- struct got_repository *, const char *);
+ struct got_repository *, const char *);
+
+/* Dispose of an object. */
void got_object_close(struct got_object *);
+
+/*
+ * Attempt to open a commit object in a repository.
+ * The provided object must be of type GOT_OBJ_TYPE_COMMIT.
+ * The caller must dispose of the commit with got_object_commit_close().
+ */
const struct got_error *got_object_commit_open(struct got_commit_object **,
struct got_repository *, struct got_object *);
+
+/* Dispose of a commit object. */
void got_object_commit_close(struct got_commit_object *);
+
+/*
+ * Attempt to open a tree object in a repository.
+ * The provided object must be of type GOT_OBJ_TYPE_TREE.
+ * The caller must dispose of the tree with got_object_tree_close().
+ */
const struct got_error *got_object_tree_open(struct got_tree_object **,
struct got_repository *, struct got_object *);
+
+/* Dispose of a tree object. */
void got_object_tree_close(struct got_tree_object *);
+
+/*
+ * Attempt to open a blob object in a repository.
+ * The provided object must be of type GOT_OBJ_TYPE_BLOB.
+ * The size_t argument specifies the block size of an associated read buffer.
+ * The caller must dispose of the blob with got_object_blob_close().
+ */
const struct got_error *got_object_blob_open(struct got_blob_object **,
struct got_repository *, struct got_object *, size_t);
+
+/* Dispose of a blob object. */
void got_object_blob_close(struct got_blob_object *);
+
+/*
+ * Write the string representation of the object ID of a blob to a buffer.
+ * The size_t argument speficies the size of the buffer. In the current
+ * implementation, it must be at least SHA1_DIGEST_STRING_LENGTH bytes.
+ * XXX This is a bad API, use got_object_id_str() instead.
+ */
char *got_object_blob_id_str(struct got_blob_object*, char *, size_t);
+
+/*
+ * Get the length of header data at the beginning of the blob's read buffer.
+ * Note that header data is only present upon the first invocation of
+ * got_object_blob_read_block() after the blob is opened.
+ */
size_t got_object_blob_get_hdrlen(struct got_blob_object *);
+
+/*
+ * Get a pointer to the blob's read buffer.
+ * The read buffer is filled by got_object_blob_read_block().
+ */
const uint8_t *got_object_blob_get_read_buf(struct got_blob_object *);
+
+/*
+ * Read the next chunk of data from a blob, up to the blob's read buffer
+ * block size. The size_t output argument indicates how many bytes have
+ * been read into the blob's read buffer. Zero bytes will be reported if
+ * all data in the blob has been read.
+ */
const struct got_error *got_object_blob_read_block(size_t *,
struct got_blob_object *);
diff --git a/include/got_reference.h b/include/got_reference.h
index 9c30c84..d8b1b74 100644
--- a/include/got_reference.h
+++ b/include/got_reference.h
@@ -26,10 +26,25 @@ struct got_reference;
struct got_repository;
struct got_object_id;
+/*
+ * Attempt to open the reference with the provided name in a repository.
+ * The caller must dispose of it with got_ref_close().
+ */
const struct got_error * got_ref_open(struct got_reference **,
struct got_repository *, const char *);
+
+/* Dispose of a reference. */
void got_ref_close(struct got_reference *);
+
+/*
+ * Create a duplicate copy of a reference.
+ * The caller must dispose of this copy with got_ref_close().
+ */
struct got_reference *got_ref_dup(struct got_reference *);
+
+/* Attempt to resolve a reference to an object ID. */
const struct got_error *got_ref_resolve(struct got_object_id **,
struct got_repository *, struct got_reference *);
+
+/* Return a string representation of a reference. */
char *got_ref_to_str(struct got_reference *);
diff --git a/include/got_repository.h b/include/got_repository.h
index 96f1b71..c60c51c 100644
--- a/include/got_repository.h
+++ b/include/got_repository.h
@@ -16,10 +16,14 @@
struct got_repository;
-/* Open and close git repositories. */
+/* Open and close repositories. */
const struct got_error *got_repo_open(struct got_repository**, const char *);
void got_repo_close(struct got_repository*);
+/*
+ * Obtain paths to various directories within a repository.
+ * The caller must dispose of a path with free(3).
+ */
char *got_repo_get_path(struct got_repository *);
char *got_repo_get_path_git_dir(struct got_repository *);
char *got_repo_get_path_objects(struct got_repository *);
@@ -28,6 +32,9 @@ char *got_repo_get_path_refs(struct got_repository *);
struct got_reference;
-/* Get a reference, by name, from a repository. */
+/*
+ * Obtain a reference, by name, from a repository.
+ * The caller must dispose of it with got_ref_close().
+ */
const struct got_error *got_repo_get_reference(struct got_reference **,
struct got_repository *, const char *);
diff --git a/include/got_worktree.h b/include/got_worktree.h
index 9031acf..f4b03a4 100644
--- a/include/got_worktree.h
+++ b/include/got_worktree.h
@@ -16,13 +16,49 @@
struct got_worktree;
+/*
+ * Attempt to initialize a new work tree on disk.
+ * The first argument is the path to a directory where the work tree
+ * will be created. The path itself must not yet exist, but the dirname(3)
+ * of the path must already exist.
+ * The reference provided will be used as the new worktree's HEAD.
+ * The third argument speficies the work tree's path prefix.
+ */
const struct got_error *got_worktree_init(const char *, struct got_reference *,
const char *, struct got_repository *);
+
+/*
+ * Attempt to open a worktree at the specified path.
+ * The caller must dispose of it with got_worktree_close().
+ */
const struct got_error *got_worktree_open(struct got_worktree **, const char *);
+
+/* Dispose of an open work tree. */
void got_worktree_close(struct got_worktree *);
+
+/*
+ * Get the path to the repository associated with a worktree.
+ * The caller must dispose of it with free(3).
+ */
char *got_worktree_get_repo_path(struct got_worktree *);
+
+/*
+ * Get the name of a work tree's HEAD reference.
+ * The caller must dispose of it with free(3).
+ */
char *got_worktree_get_head_ref_name(struct got_worktree *);
+
+/* A callback function which is invoked when a path is checked out. */
typedef void (*got_worktree_checkout_cb)(void *, const char *);
+
+/*
+ * Attempt to check out files into a work tree from its associated repository
+ * and path prefix, and update the work tree's file index accordingly.
+ * File content is obtained from blobs within the work tree's path prefix
+ * inside the tree resolved via the provided reference.
+ * The checkout progress callback will be invoked with the provided
+ * void * argument, and the path of each checked out file.
+ */
const struct got_error *got_worktree_checkout_files(struct got_worktree *,
struct got_reference *, struct got_repository *,
- got_worktree_checkout_cb progress_cb, void *progress_arg);
+ got_worktree_checkout_cb progress, void *);