include/git2/object.h

   1 /*
   2  * Copyright (C) the libgit2 contributors. All rights reserved.
   3  *
   4  * This file is part of libgit2, distributed under the GNU GPL v2 with
   5  * a Linking Exception. For full terms see the included COPYING file.
   6  */
   7 #ifndef INCLUDE_git_object_h__
   8 #define INCLUDE_git_object_h__
   9
  10 #include "common.h"
  11 #include "types.h"
  12 #include "oid.h"
  13 #include "buffer.h"
  14
  15 /**
  16  * @file git2/object.h
  17  * @brief Git revision object management routines
  18  * @defgroup git_object Git revision object management routines
  19  * @ingroup Git
  20  * @{
  21  */
  22 GIT_BEGIN_DECL
  23
  24 /**
  25  * Lookup a reference to one of the objects in a repository.
  26  *
  27  * The generated reference is owned by the repository and
  28  * should be closed with the `git_object_free` method
  29  * instead of free'd manually.
  30  *
  31  * The 'type' parameter must match the type of the object
  32  * in the odb; the method will fail otherwise.
  33  * The special value 'GIT_OBJ_ANY' may be passed to let
  34  * the method guess the object's type.
  35  *
  36  * @param object pointer to the looked-up object
  37  * @param repo the repository to look up the object
  38  * @param id the unique identifier for the object
  39  * @param type the type of the object
  40  * @return 0 or an error code
  41  */
  42 GIT_EXTERN(int) git_object_lookup(
  43                 git_object **object,
  44                 git_repository *repo,
  45                 const git_oid *id,
  46                 git_otype type);
  47
  48 /**
  49  * Lookup a reference to one of the objects in a repository,
  50  * given a prefix of its identifier (short id).
  51  *
  52  * The object obtained will be so that its identifier
  53  * matches the first 'len' hexadecimal characters
  54  * (packets of 4 bits) of the given 'id'.
  55  * 'len' must be at least GIT_OID_MINPREFIXLEN, and
  56  * long enough to identify a unique object matching
  57  * the prefix; otherwise the method will fail.
  58  *
  59  * The generated reference is owned by the repository and
  60  * should be closed with the `git_object_free` method
  61  * instead of free'd manually.
  62  *
  63  * The 'type' parameter must match the type of the object
  64  * in the odb; the method will fail otherwise.
  65  * The special value 'GIT_OBJ_ANY' may be passed to let
  66  * the method guess the object's type.
  67  *
  68  * @param object_out pointer where to store the looked-up object
  69  * @param repo the repository to look up the object
  70  * @param id a short identifier for the object
  71  * @param len the length of the short identifier
  72  * @param type the type of the object
  73  * @return 0 or an error code
  74  */
  75 GIT_EXTERN(int) git_object_lookup_prefix(
  76                 git_object **object_out,
  77                 git_repository *repo,
  78                 const git_oid *id,
  79                 size_t len,
  80                 git_otype type);
  81
  82
  83 /**
  84  * Lookup an object that represents a tree entry.
  85  *
  86  * @param out buffer that receives a pointer to the object (which must be freed
  87  *            by the caller)
  88  * @param treeish root object that can be peeled to a tree
  89  * @param path relative path from the root object to the desired object
  90  * @param type type of object desired
  91  * @return 0 on success, or an error code
  92  */
  93 GIT_EXTERN(int) git_object_lookup_bypath(
  94                 git_object **out,
  95                 const git_object *treeish,
  96                 const char *path,
  97                 git_otype type);
  98
  99 /**
 100  * Get the id (SHA1) of a repository object
 101  *
 102  * @param obj the repository object
 103  * @return the SHA1 id
 104  */
 105 GIT_EXTERN(const git_oid *) git_object_id(const git_object *obj);
 106
 107 /**
 108  * Get a short abbreviated OID string for the object
 109  *
 110  * @param out Buffer to write string into
 111  * @param obj The object to get an ID for
 112  * @return 0 on success, <0 for error
 113  */
 114 GIT_EXTERN(int) git_object_short_id(git_buf *out, const git_object *obj);
 115
 116 /**
 117  * Get the object type of an object
 118  *
 119  * @param obj the repository object
 120  * @return the object's type
 121  */
 122 GIT_EXTERN(git_otype) git_object_type(const git_object *obj);
 123
 124 /**
 125  * Get the repository that owns this object
 126  *
 127  * Freeing or calling `git_repository_close` on the
 128  * returned pointer will invalidate the actual object.
 129  *
 130  * Any other operation may be run on the repository without
 131  * affecting the object.
 132  *
 133  * @param obj the object
 134  * @return the repository who owns this object
 135  */
 136 GIT_EXTERN(git_repository *) git_object_owner(const git_object *obj);
 137
 138 /**
 139  * Close an open object
 140  *
 141  * This method instructs the library to close an existing
 142  * object; note that git_objects are owned and cached by the repository
 143  * so the object may or may not be freed after this library call,
 144  * depending on how aggressive is the caching mechanism used
 145  * by the repository.
 146  *
 147  * IMPORTANT:
 148  * It *is* necessary to call this method when you stop using
 149  * an object. Failure to do so will cause a memory leak.
 150  *
 151  * @param object the object to close
 152  */
 153 GIT_EXTERN(void) git_object_free(git_object *object);
 154
 155 /**
 156  * Convert an object type to it's string representation.
 157  *
 158  * The result is a pointer to a string in static memory and
 159  * should not be free()'ed.
 160  *
 161  * @param type object type to convert.
 162  * @return the corresponding string representation.
 163  */
 164 GIT_EXTERN(const char *) git_object_type2string(git_otype type);
 165
 166 /**
 167  * Convert a string object type representation to it's git_otype.
 168  *
 169  * @param str the string to convert.
 170  * @return the corresponding git_otype.
 171  */
 172 GIT_EXTERN(git_otype) git_object_string2type(const char *str);
 173
 174 /**
 175  * Determine if the given git_otype is a valid loose object type.
 176  *
 177  * @param type object type to test.
 178  * @return true if the type represents a valid loose object type,
 179  * false otherwise.
 180  */
 181 GIT_EXTERN(int) git_object_typeisloose(git_otype type);
 182
 183 /**
 184  * Get the size in bytes for the structure which
 185  * acts as an in-memory representation of any given
 186  * object type.
 187  *
 188  * For all the core types, this would the equivalent
 189  * of calling `sizeof(git_commit)` if the core types
 190  * were not opaque on the external API.
 191  *
 192  * @param type object type to get its size
 193  * @return size in bytes of the object
 194  */
 195 GIT_EXTERN(size_t) git_object__size(git_otype type);
 196
 197 /**
 198  * Recursively peel an object until an object of the specified type is met.
 199  *
 200  * The retrieved `peeled` object is owned by the repository and should be
 201  * closed with the `git_object_free` method.
 202  *
 203  * If you pass `GIT_OBJ_ANY` as the target type, then the object will be
 204  * peeled until the type changes (e.g. a tag will be chased until the
 205  * referenced object is no longer a tag).
 206  *
 207  * @param peeled Pointer to the peeled git_object
 208  * @param object The object to be processed
 209  * @param target_type The type of the requested object (GIT_OBJ_COMMIT,
 210  * GIT_OBJ_TAG, GIT_OBJ_TREE, GIT_OBJ_BLOB or GIT_OBJ_ANY).
 211  * @return 0 on success, GIT_EAMBIGUOUS, GIT_ENOTFOUND or an error code
 212  */
 213 GIT_EXTERN(int) git_object_peel(
 214         git_object **peeled,
 215         const git_object *object,
 216         git_otype target_type);
 217
 218 /**
 219  * Create an in-memory copy of a Git object. The copy must be
 220  * explicitly free'd or it will leak.
 221  *
 222  * @param dest Pointer to store the copy of the object
 223  * @param source Original object to copy
 224  */
 225 GIT_EXTERN(int) git_object_dup(git_object **dest, git_object *source);
 226
 227 /** @} */
 228 GIT_END_DECL
 229
 230 #endif