commit 0c60ce5ab29975b198dec154bc2ebbea83916eb9 from: Stefan Sperling date: Mon Apr 02 09:10:05 2018 UTC document the current public API commit - 97128b573c12726495716f9f6a31a57d4b1b06fd commit + 0c60ce5ab29975b198dec154bc2ebbea83916eb9 blob - f7ac2b2b5716ca262b954e9c56dd05936fc04e3f blob + 4673b9c5bf89bc6b2ed60ed83a5a1ee337865617 --- include/got_diff.h +++ include/got_diff.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2017 Stefan Sperling + * Copyright (c) 2018 Stefan Sperling * * 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 *); blob - ad4669b8af10e9550be1ac1e704c3103fe2a4717 blob + 4927b6057d86838ccd49bf408dff0712446eec31 --- include/got_error.h +++ 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); blob - 2b3af389c809b5bfa2e2d23457718e1de4f0b696 blob + 335f73e9a107a9edecc20e1398b3d4641dbd9111 --- include/got_object.h +++ 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 *); blob - 9c30c84496b4423c3a5d3cb3282db636b246c4d3 blob + d8b1b74a97c6609fa5a8d85c2e75cb27f3c96171 --- include/got_reference.h +++ 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 *); blob - 96f1b71b451b24b056f5bb16b7cf978bfc6dc5e1 blob + c60c51ce815bea1a4ee25e038ac6d97210ae026b --- include/got_repository.h +++ 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 *); blob - 9031acfb6d57082ebb9029f76a986a9545eb4912 blob + f4b03a494564fac33bc5f2de11b332218ec37eed --- include/got_worktree.h +++ 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 *);