9it-objutils.3

.TH 9IT-OBJUTILS 3 2021-01-03 9it-0.1
.SH NAME
write_blob, write_tree, write_commit, read_tree, read_commit, hash_tree, hash_commit, add_index_item, add_index_dir, clear_index, read_index, get_head_commit, get_cur_branch, read_ref, write_ref
.SH DESCRIPTION
This is the developer man page for the header file objutils.h. For 9it usage, please refer to 9it (1).
.SH SYNOPSIS
.nf
#include "headers/objutils.h"

\fBint write_blob(char* \fIfile_path\fR);\fP
\fBint write_tree(Tree* \fItree\fR);\fP
\fBint write_commit(Commit* \fIcommit\fR);\fP

\fBint read_tree(Tree* \fIroot\fR);\fP
\fBint read_commit(Commit* \fIcommit\fR);\fP

\fBint hash_tree(Tree* \fItree\fR);\fP
\fBint hash_commit(Commit* \fIcommit\fR);\fP

\fBint add_index_item(char* \fIfile_path\fR);\fP
\fBint add_index_dir(char* \fIfile_path\fR);\fP
\fBint clear_index(void);\fP
\fBIndex* read_index(void);\fP

\fBunsigned char* get_head_commit(void);\fP
\fBchar* get_cur_branch(void);\fP
\fBunsigned char* read_ref(char* \fIbranch_name\fR);\fP
\fBint write_ref(char* \fIbranch_name\fR, unsigned char* \fIhash\fk);\fP


.fi
.SH DESCRIPTION
\fBwrite_blob\fP hashes and compresses a file and writes the blob into the 9it objects directory. \fBwrite_tree\fP and \fBwrite_commit\fP are similar but they don't perform any hashing. The caller must hash the structs themselves (perhaps by calling \fBhash_tree\fP and \fBhash_commit\fP) and set the hash field in the respective structs. Keep in mind that \fBwrite_tree\fP is not recursive, it will not write children trees. For more information on the structure of the binary that is written into objects, see 9it-format (5).

\fBread_tree\fP and \fBread_commit\fP requires that the hash field of the Tree/Commit that is passed in to be set, as that is what it uses to find the file to read. For \fBread_tree\fP, if the tree is the root, the name field is also not set. In addition, this function is NOT recursive, it will partially create the children of the tree that is read. Specifically, the name and hash of the children will be set, but the children of the children will be empty regardless if they have children or not. The caller must iterate through the children and call this function on them.

\fBhash_tree\fP and \fBhash_commit\fP will hash the respective structs and set the hash field of the structs as a result.

\fBadd_index_item\fP adds a file to the index, whereas \fBadd_index_dir\fP recursively adds all files in the directory supplied. The path supplied must be relative to the repository root. In addition, it is the caller's responsibility to ensure that the path passed to \fBadd_index_item\fP is indeed a file and not a directory. \fBclear_index\fP simply reinitializes the index. \fBread_index\fP just reads the index file.

\fBget_head_commit\fP grabs the hash of the latest commit on the current branch. \fBget_cur_branchf\fP gets the name of the current branch. \fBread_ref\fP reads the latest commit of the branch passed in. Finally, \fBwrite_ref\fB updates the latest commit of the desired branch.

.SH RETURN VALUE
All write and read functions, as well as most of the index functions, return 0 on success and -1 on failure. If the object already existed before the write, 0 is still returned and no write is done.

\fBget_head_commit\fP as well as \fBread_ref\fP returns a hash, which is an unsigned char array of length SHA_DIGEST_LENGTH, which is not null terminated. This must be freed by the caller. On error, null is returned. \fBget_cur_branch\fP returns a malloced null terminated string, on error, null is returned.