object.h

Branch :
Show log
Commit
Author : Edward Thomson
Date : 2026-05-12 23:23:21
Hash : 605f34a0
Message : sha256: it's what's for breakfast Make the SHA256 support on by default.
include/git2/object.h
/*
 * Copyright (C) the libgit2 contributors. All rights reserved.
 *
 * This file is part of libgit2, distributed under the GNU GPL v2 with
 * a Linking Exception. For full terms see the included COPYING file.
 */
#ifndef INCLUDE_git_object_h__
#define INCLUDE_git_object_h__

#include "common.h"
#include "types.h"
#include "oid.h"
#include "buffer.h"
#include "filter.h"

/**
 * @file git2/object.h
 * @brief Objects are blobs (files), trees (directories), commits, and annotated tags
 * @defgroup git_object Git revision object management routines
 * @ingroup Git
 * @{
 */
GIT_BEGIN_DECL

/** Maximum size of a git object */
#define GIT_OBJECT_SIZE_MAX UINT64_MAX

/**
 * Lookup a reference to one of the objects in a repository.
 *
 * The generated reference is owned by the repository and
 * should be closed with the `git_object_free` method
 * instead of free'd manually.
 *
 * The 'type' parameter must match the type of the object
 * in the odb; the method will fail otherwise.
 * The special value 'GIT_OBJECT_ANY' may be passed to let
 * the method guess the object's type.
 *
 * @param[out] object pointer to the looked-up object
 * @param repo the repository to look up the object
 * @param id the unique identifier for the object
 * @param type the type of the object
 * @return 0 or an error code
 */
GIT_EXTERN(int) git_object_lookup(
		git_object **object,
		git_repository *repo,
		const git_oid *id,
		git_object_t type);

/**
 * Lookup a reference to one of the objects in a repository,
 * given a prefix of its identifier (short id).
 *
 * The object obtained will be so that its identifier
 * matches the first 'len' hexadecimal characters
 * (packets of 4 bits) of the given `id`. `len` must be
 * at least `GIT_OID_MINPREFIXLEN`, and long enough to
 * identify a unique object matching the prefix; otherwise
 * the method will fail.
 *
 * The generated reference is owned by the repository and
 * should be closed with the `git_object_free` method
 * instead of free'd manually.
 *
 * The `type` parameter must match the type of the object
 * in the odb; the method will fail otherwise.
 * The special value `GIT_OBJECT_ANY` may be passed to let
 * the method guess the object's type.
 *
 * @param[out] object_out pointer where to store the looked-up object
 * @param repo the repository to look up the object
 * @param id a short identifier for the object
 * @param len the length of the short identifier
 * @param type the type of the object
 * @return 0 or an error code
 */
GIT_EXTERN(int) git_object_lookup_prefix(
		git_object **object_out,
		git_repository *repo,
		const git_oid *id,
		size_t len,
		git_object_t type);


/**
 * Lookup an object that represents a tree entry.
 *
 * @param[out] out buffer that receives a pointer to the object
 *             (which must be freed by the caller)
 * @param treeish root object that can be peeled to a tree
 * @param path relative path from the root object to the desired object
 * @param type type of object desired
 * @return 0 on success, or an error code
 */
GIT_EXTERN(int) git_object_lookup_bypath(
		git_object **out,
		const git_object *treeish,
		const char *path,
		git_object_t type);

/**
 * Get the id (SHA1) of a repository object
 *
 * @param obj the repository object
 * @return the SHA1 id
 */
GIT_EXTERN(const git_oid *) git_object_id(const git_object *obj);

/**
 * Get a short abbreviated OID string for the object
 *
 * This starts at the "core.abbrev" length (default 7 characters) and
 * iteratively extends to a longer string if that length is ambiguous.
 * The result will be unambiguous (at least until new objects are added to
 * the repository).
 *
 * @param out Buffer to write string into
 * @param obj The object to get an ID for
 * @return 0 on success, <0 for error
 */
GIT_EXTERN(int) git_object_short_id(git_buf *out, const git_object *obj);

/**
 * Get the object type of an object
 *
 * @param obj the repository object
 * @return the object's type
 */
GIT_EXTERN(git_object_t) git_object_type(const git_object *obj);

/**
 * Get the repository that owns this object
 *
 * Freeing or calling `git_repository_close` on the
 * returned pointer will invalidate the actual object.
 *
 * Any other operation may be run on the repository without
 * affecting the object.
 *
 * @param obj the object
 * @return the repository who owns this object
 */
GIT_EXTERN(git_repository *) git_object_owner(const git_object *obj);

/**
 * Close an open object
 *
 * This method instructs the library to close an existing
 * object; note that git_objects are owned and cached by the repository
 * so the object may or may not be freed after this library call,
 * depending on how aggressive is the caching mechanism used
 * by the repository.
 *
 * IMPORTANT:
 * It *is* necessary to call this method when you stop using
 * an object. Failure to do so will cause a memory leak.
 *
 * @param object the object to close
 */
GIT_EXTERN(void) git_object_free(git_object *object);

/**
 * Convert an object type to its string representation.
 *
 * The result is a pointer to a string in static memory and
 * should not be free()'ed.
 *
 * @param type object type to convert.
 * @return the corresponding string representation.
 */
GIT_EXTERN(const char *) git_object_type2string(git_object_t type);

/**
 * Convert a string object type representation to it's git_object_t.
 *
 * @param str the string to convert.
 * @return the corresponding git_object_t.
 */
GIT_EXTERN(git_object_t) git_object_string2type(const char *str);

/**
 * Determine if the given git_object_t is a valid object type.
 *
 * @param type object type to test.
 * @return 1 if the type represents a valid loose object type, 0 otherwise
 */
GIT_EXTERN(int) git_object_type_is_valid(git_object_t type);

/**
 * Recursively peel an object until an object of the specified type is met.
 *
 * If the query cannot be satisfied due to the object model,
 * GIT_EINVALIDSPEC will be returned (e.g. trying to peel a blob to a
 * tree).
 *
 * If you pass `GIT_OBJECT_ANY` as the target type, then the object will
 * be peeled until the type changes. A tag will be peeled until the
 * referenced object is no longer a tag, and a commit will be peeled
 * to a tree. Any other object type will return GIT_EINVALIDSPEC.
 *
 * If peeling a tag we discover an object which cannot be peeled to
 * the target type due to the object model, GIT_EPEEL will be
 * returned.
 *
 * You must free the returned object.
 *
 * @param peeled Pointer to the peeled git_object
 * @param object The object to be processed
 * @param target_type The type of the requested object (a GIT_OBJECT_ value)
 * @return 0 on success, GIT_EINVALIDSPEC, GIT_EPEEL, or an error code
 */
GIT_EXTERN(int) git_object_peel(
	git_object **peeled,
	const git_object *object,
	git_object_t target_type);

/**
 * Create an in-memory copy of a Git object. The copy must be
 * explicitly free'd or it will leak.
 *
 * @param[out] dest Pointer to store the copy of the object
 * @param source Original object to copy
 * @return 0 or an error code
 */
GIT_EXTERN(int) git_object_dup(git_object **dest, git_object *source);

/**
 * Options for calculating object IDs from raw content.
 *
 * Initialize with `GIT_OBJECT_ID_OPTIONS_INIT`. Alternatively, you can
 * use `git_object_id_options_init`.
 *
 * @options[version] GIT_OBJECT_ID_OPTIONS_VERSION
 * @options[init_macro] GIT_OBJECT_ID_OPTIONS_INIT
 * @options[init_function] git_object_id_options_init
 */
typedef struct {
	unsigned int version; /**< version for the struct */

	/**
	 * Object type of the raw content; if not specified, this
	 * defaults to `GIT_OBJECT_BLOB`.
	 */
	git_object_t object_type;

	/**
	 * Object ID type to generate; if not specified, this defaults
	 * to `GIT_OID_DEFAULT`.
	 */
	git_oid_t oid_type;

	/**
	 * Filters to mutate the raw data with; these are ignored
	 * unless the given raw object data is a blob.
	 */
	git_filter_list *filters;
} git_object_id_options;

/** Current version for the `git_object_id_options` structure */
#define GIT_OBJECT_ID_OPTIONS_VERSION 1

/** Static constructor for `object_id_options` */
#define GIT_OBJECT_ID_OPTIONS_INIT {GIT_OBJECT_ID_OPTIONS_VERSION}

/**
 * Initialize `git_object_id_options` structure with default values.
 * Equivalent to creating an instance with `GIT_WORKTREE_ADD_OPTIONS_INIT`.
 *
 * @param opts The `git_object_id_options` struct to initialize.
 * @param version The struct version; pass `GIT_OBJECT_ID_OPTIONS_INIT`.
 * @return 0 on success; -1 on failure.
 */
GIT_EXTERN(int) git_object_id_options_init(git_object_id_options *opts,
	unsigned int version);

/**
 * Given the raw content of an object, determine the object ID.
 * This prepends the object header to the given data, and hashes
 * the results with the hash corresponding to the given oid_type.
 *
 * @param[out] oid_out the resulting object id
 * @param buf the raw object content
 * @param len the length of the given buffer
 * @param opts the options for id calculation
 * @return 0 on success, or an error code
 */
GIT_EXTERN(int) git_object_id_from_buffer(
	git_oid *oid_out,
	const void *buf,
	size_t len,
	const git_object_id_options *opts);

/**
 * Given an on-disk file that contains the raw content of an object,
 * determine the object ID. This prepends the object header to the given
 * data, and hashes the results with the hash corresponding to the given
 * oid_type.
 *
 * Note that this does not look at attributes or do any on-disk filtering
 * (like line ending translation), so when used with blobs, it may not
 * match the results for adding to the repository. To compute the object
 * ID for a blob with filters, use `git_repository_hashfile`.
 *
 * @see git_repository_hashfile
 *
 * @param[out] oid_out the resulting object id
 * @param path the on-disk path to the raw object content
 * @param opts the options for id calculation
 * @return 0 on success, or an error code
 */
GIT_EXTERN(int) git_object_id_from_file(
	git_oid *oid_out,
	const char *path,
	const git_object_id_options *opts);

/**
 * Analyzes a buffer of raw object content and determines its validity.
 * Tree, commit, and tag objects will be parsed and ensured that they
 * are valid, parseable content.  (Blobs are always valid by definition.)
 * An error message will be set with an informative message if the object
 * is not valid.
 *
 * @warning This function is experimental and its signature may change in
 * the future.
 *
 * @param valid Output pointer to set with validity of the object content
 * @param buf The contents to validate
 * @param len The length of the buffer
 * @param object_type The type of the object in the buffer
 * @param oid_type The object ID type for the OIDs in the given buffer
 * @return 0 on success or an error code
 */
GIT_EXTERN(int) git_object_rawcontent_is_valid(
	int *valid,
	const char *buf,
	size_t len,
	git_object_t object_type,
	git_oid_t oid_type);

/** @} */
GIT_END_DECL

#endif
kc3-lang/libgit2/include/git2/object.h

Commit
