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  * This starts at the "core.abbrev" length (default 7 characters) and
 111  * iteratively extends to a longer string if that length is ambiguous.
 112  * The result will be unambiguous (at least until new objects are added to
 113  * the repository).
 114  *
 115  * @param out Buffer to write string into
 116  * @param obj The object to get an ID for
 117  * @return 0 on success, <0 for error
 118  */
 119 GIT_EXTERN(int) git_object_short_id(git_buf *out, const git_object *obj);
 120
 121 /**
 122  * Get the object type of an object
 123  *
 124  * @param obj the repository object
 125  * @return the object's type
 126  */
 127 GIT_EXTERN(git_otype) git_object_type(const git_object *obj);
 128
 129 /**
 130  * Get the repository that owns this object
 131  *
 132  * Freeing or calling `git_repository_close` on the
 133  * returned pointer will invalidate the actual object.
 134  *
 135  * Any other operation may be run on the repository without
 136  * affecting the object.
 137  *
 138  * @param obj the object
 139  * @return the repository who owns this object
 140  */
 141 GIT_EXTERN(git_repository *) git_object_owner(const git_object *obj);
 142
 143 /**
 144  * Close an open object
 145  *
 146  * This method instructs the library to close an existing
 147  * object; note that git_objects are owned and cached by the repository
 148  * so the object may or may not be freed after this library call,
 149  * depending on how aggressive is the caching mechanism used
 150  * by the repository.
 151  *
 152  * IMPORTANT:
 153  * It *is* necessary to call this method when you stop using
 154  * an object. Failure to do so will cause a memory leak.
 155  *
 156  * @param object the object to close
 157  */
 158 GIT_EXTERN(void) git_object_free(git_object *object);
 159
 160 /**
 161  * Convert an object type to its string representation.
 162  *
 163  * The result is a pointer to a string in static memory and
 164  * should not be free()'ed.
 165  *
 166  * @param type object type to convert.
 167  * @return the corresponding string representation.
 168  */
 169 GIT_EXTERN(const char *) git_object_type2string(git_otype type);
 170
 171 /**
 172  * Convert a string object type representation to it's git_otype.
 173  *
 174  * @param str the string to convert.
 175  * @return the corresponding git_otype.
 176  */
 177 GIT_EXTERN(git_otype) git_object_string2type(const char *str);
 178
 179 /**
 180  * Determine if the given git_otype is a valid loose object type.
 181  *
 182  * @param type object type to test.
 183  * @return true if the type represents a valid loose object type,
 184  * false otherwise.
 185  */
 186 GIT_EXTERN(int) git_object_typeisloose(git_otype type);
 187
 188 /**
 189  * Get the size in bytes for the structure which
 190  * acts as an in-memory representation of any given
 191  * object type.
 192  *
 193  * For all the core types, this would the equivalent
 194  * of calling `sizeof(git_commit)` if the core types
 195  * were not opaque on the external API.
 196  *
 197  * @param type object type to get its size
 198  * @return size in bytes of the object
 199  */
 200 GIT_EXTERN(size_t) git_object__size(git_otype type);
 201
 202 /**
 203  * Recursively peel an object until an object of the specified type is met.
 204  *
 205  * The retrieved `peeled` object is owned by the repository and should be
 206  * closed with the `git_object_free` method.
 207  *
 208  * If you pass `GIT_OBJ_ANY` as the target type, then the object will be
 209  * peeled until the type changes (e.g. a tag will be chased until the
 210  * referenced object is no longer a tag).
 211  *
 212  * @param peeled Pointer to the peeled git_object
 213  * @param object The object to be processed
 214  * @param target_type The type of the requested object (GIT_OBJ_COMMIT,
 215  * GIT_OBJ_TAG, GIT_OBJ_TREE, GIT_OBJ_BLOB or GIT_OBJ_ANY).
 216  * @return 0 on success, GIT_EAMBIGUOUS, GIT_ENOTFOUND or an error code
 217  */
 218 GIT_EXTERN(int) git_object_peel(
 219         git_object **peeled,
 220         const git_object *object,
 221         git_otype target_type);
 222
 223 /**
 224  * Create an in-memory copy of a Git object. The copy must be
 225  * explicitly free'd or it will leak.
 226  *
 227  * @param dest Pointer to store the copy of the object
 228  * @param source Original object to copy
 229  */
 230 GIT_EXTERN(int) git_object_dup(git_object **dest, git_object *source);
 231
 232 /** @} */
 233 GIT_END_DECL
 234
 235 #endif