include/git2/object.h

0001 /*
0002  * Copyright (C) the libgit2 contributors. All rights reserved.
0003  *
0004  * This file is part of libgit2, distributed under the GNU GPL v2 with
0005  * a Linking Exception. For full terms see the included COPYING file.
0006  */
0007 #ifndef INCLUDE_git_object_h__
0008 #define INCLUDE_git_object_h__
0009
0010 #include "common.h"
0011 #include "types.h"
0012 #include "oid.h"
0013 #include "buffer.h"
0014
0015 /**
0016  * @file git2/object.h
0017  * @brief Git revision object management routines
0018  * @defgroup git_object Git revision object management routines
0019  * @ingroup Git
0020  * @{
0021  */
0022 GIT_BEGIN_DECL
0023
0024 #define GIT_OBJECT_SIZE_MAX UINT64_MAX
0025
0026 /**
0027  * Lookup a reference to one of the objects in a repository.
0028  *
0029  * The generated reference is owned by the repository and
0030  * should be closed with the `git_object_free` method
0031  * instead of free'd manually.
0032  *
0033  * The 'type' parameter must match the type of the object
0034  * in the odb; the method will fail otherwise.
0035  * The special value 'GIT_OBJECT_ANY' may be passed to let
0036  * the method guess the object's type.
0037  *
0038  * @param object pointer to the looked-up object
0039  * @param repo the repository to look up the object
0040  * @param id the unique identifier for the object
0041  * @param type the type of the object
0042  * @return 0 or an error code
0043  */
0044 GIT_EXTERN(int) git_object_lookup(
0045         git_object **object,
0046         git_repository *repo,
0047         const git_oid *id,
0048         git_object_t type);
0049
0050 /**
0051  * Lookup a reference to one of the objects in a repository,
0052  * given a prefix of its identifier (short id).
0053  *
0054  * The object obtained will be so that its identifier
0055  * matches the first 'len' hexadecimal characters
0056  * (packets of 4 bits) of the given 'id'.
0057  * 'len' must be at least GIT_OID_MINPREFIXLEN, and
0058  * long enough to identify a unique object matching
0059  * the prefix; otherwise the method will fail.
0060  *
0061  * The generated reference is owned by the repository and
0062  * should be closed with the `git_object_free` method
0063  * instead of free'd manually.
0064  *
0065  * The 'type' parameter must match the type of the object
0066  * in the odb; the method will fail otherwise.
0067  * The special value 'GIT_OBJECT_ANY' may be passed to let
0068  * the method guess the object's type.
0069  *
0070  * @param object_out pointer where to store the looked-up object
0071  * @param repo the repository to look up the object
0072  * @param id a short identifier for the object
0073  * @param len the length of the short identifier
0074  * @param type the type of the object
0075  * @return 0 or an error code
0076  */
0077 GIT_EXTERN(int) git_object_lookup_prefix(
0078         git_object **object_out,
0079         git_repository *repo,
0080         const git_oid *id,
0081         size_t len,
0082         git_object_t type);
0083
0084
0085 /**
0086  * Lookup an object that represents a tree entry.
0087  *
0088  * @param out buffer that receives a pointer to the object (which must be freed
0089  *            by the caller)
0090  * @param treeish root object that can be peeled to a tree
0091  * @param path relative path from the root object to the desired object
0092  * @param type type of object desired
0093  * @return 0 on success, or an error code
0094  */
0095 GIT_EXTERN(int) git_object_lookup_bypath(
0096         git_object **out,
0097         const git_object *treeish,
0098         const char *path,
0099         git_object_t type);
0100
0101 /**
0102  * Get the id (SHA1) of a repository object
0103  *
0104  * @param obj the repository object
0105  * @return the SHA1 id
0106  */
0107 GIT_EXTERN(const git_oid *) git_object_id(const git_object *obj);
0108
0109 /**
0110  * Get a short abbreviated OID string for the object
0111  *
0112  * This starts at the "core.abbrev" length (default 7 characters) and
0113  * iteratively extends to a longer string if that length is ambiguous.
0114  * The result will be unambiguous (at least until new objects are added to
0115  * the repository).
0116  *
0117  * @param out Buffer to write string into
0118  * @param obj The object to get an ID for
0119  * @return 0 on success, <0 for error
0120  */
0121 GIT_EXTERN(int) git_object_short_id(git_buf *out, const git_object *obj);
0122
0123 /**
0124  * Get the object type of an object
0125  *
0126  * @param obj the repository object
0127  * @return the object's type
0128  */
0129 GIT_EXTERN(git_object_t) git_object_type(const git_object *obj);
0130
0131 /**
0132  * Get the repository that owns this object
0133  *
0134  * Freeing or calling `git_repository_close` on the
0135  * returned pointer will invalidate the actual object.
0136  *
0137  * Any other operation may be run on the repository without
0138  * affecting the object.
0139  *
0140  * @param obj the object
0141  * @return the repository who owns this object
0142  */
0143 GIT_EXTERN(git_repository *) git_object_owner(const git_object *obj);
0144
0145 /**
0146  * Close an open object
0147  *
0148  * This method instructs the library to close an existing
0149  * object; note that git_objects are owned and cached by the repository
0150  * so the object may or may not be freed after this library call,
0151  * depending on how aggressive is the caching mechanism used
0152  * by the repository.
0153  *
0154  * IMPORTANT:
0155  * It *is* necessary to call this method when you stop using
0156  * an object. Failure to do so will cause a memory leak.
0157  *
0158  * @param object the object to close
0159  */
0160 GIT_EXTERN(void) git_object_free(git_object *object);
0161
0162 /**
0163  * Convert an object type to its string representation.
0164  *
0165  * The result is a pointer to a string in static memory and
0166  * should not be free()'ed.
0167  *
0168  * @param type object type to convert.
0169  * @return the corresponding string representation.
0170  */
0171 GIT_EXTERN(const char *) git_object_type2string(git_object_t type);
0172
0173 /**
0174  * Convert a string object type representation to it's git_object_t.
0175  *
0176  * @param str the string to convert.
0177  * @return the corresponding git_object_t.
0178  */
0179 GIT_EXTERN(git_object_t) git_object_string2type(const char *str);
0180
0181 /**
0182  * Determine if the given git_object_t is a valid loose object type.
0183  *
0184  * @param type object type to test.
0185  * @return true if the type represents a valid loose object type,
0186  * false otherwise.
0187  */
0188 GIT_EXTERN(int) git_object_typeisloose(git_object_t type);
0189
0190 /**
0191  * Recursively peel an object until an object of the specified type is met.
0192  *
0193  * If the query cannot be satisfied due to the object model,
0194  * GIT_EINVALIDSPEC will be returned (e.g. trying to peel a blob to a
0195  * tree).
0196  *
0197  * If you pass `GIT_OBJECT_ANY` as the target type, then the object will
0198  * be peeled until the type changes. A tag will be peeled until the
0199  * referenced object is no longer a tag, and a commit will be peeled
0200  * to a tree. Any other object type will return GIT_EINVALIDSPEC.
0201  *
0202  * If peeling a tag we discover an object which cannot be peeled to
0203  * the target type due to the object model, GIT_EPEEL will be
0204  * returned.
0205  *
0206  * You must free the returned object.
0207  *
0208  * @param peeled Pointer to the peeled git_object
0209  * @param object The object to be processed
0210  * @param target_type The type of the requested object (a GIT_OBJECT_ value)
0211  * @return 0 on success, GIT_EINVALIDSPEC, GIT_EPEEL, or an error code
0212  */
0213 GIT_EXTERN(int) git_object_peel(
0214     git_object **peeled,
0215     const git_object *object,
0216     git_object_t target_type);
0217
0218 /**
0219  * Create an in-memory copy of a Git object. The copy must be
0220  * explicitly free'd or it will leak.
0221  *
0222  * @param dest Pointer to store the copy of the object
0223  * @param source Original object to copy
0224  * @return 0 or an error code
0225  */
0226 GIT_EXTERN(int) git_object_dup(git_object **dest, git_object *source);
0227
0228 #ifdef GIT_EXPERIMENTAL_SHA256
0229 /**
0230  * Analyzes a buffer of raw object content and determines its validity.
0231  * Tree, commit, and tag objects will be parsed and ensured that they
0232  * are valid, parseable content.  (Blobs are always valid by definition.)
0233  * An error message will be set with an informative message if the object
0234  * is not valid.
0235  *
0236  * @warning This function is experimental and its signature may change in
0237  * the future.
0238  *
0239  * @param valid Output pointer to set with validity of the object content
0240  * @param buf The contents to validate
0241  * @param len The length of the buffer
0242  * @param object_type The type of the object in the buffer
0243  * @param oid_type The object ID type for the OIDs in the given buffer
0244  * @return 0 on success or an error code
0245  */
0246 GIT_EXTERN(int) git_object_rawcontent_is_valid(
0247     int *valid,
0248     const char *buf,
0249     size_t len,
0250     git_object_t object_type,
0251     git_oid_t oid_type);
0252 #else
0253 /**
0254  * Analyzes a buffer of raw object content and determines its validity.
0255  * Tree, commit, and tag objects will be parsed and ensured that they
0256  * are valid, parseable content.  (Blobs are always valid by definition.)
0257  * An error message will be set with an informative message if the object
0258  * is not valid.
0259  *
0260  * @warning This function is experimental and its signature may change in
0261  * the future.
0262  *
0263  * @param valid Output pointer to set with validity of the object content
0264  * @param buf The contents to validate
0265  * @param len The length of the buffer
0266  * @param object_type The type of the object in the buffer
0267  * @return 0 on success or an error code
0268  */
0269 GIT_EXTERN(int) git_object_rawcontent_is_valid(
0270     int *valid,
0271     const char *buf,
0272     size_t len,
0273     git_object_t object_type);
0274 #endif
0275
0276 /** @} */
0277 GIT_END_DECL
0278
0279 #endif