mirror of
https://git.proxmox.com/git/libgit2
synced 2025-05-02 16:34:37 +00:00
bb742ede3d
1. The license header is technically not valid if it doesn't have a copyright signature. 2. The COPYING file has been updated with the different licenses used in the project. 3. The full GPLv2 header in each file annoys me.
325 lines
10 KiB
C
325 lines
10 KiB
C
/*
|
|
* Copyright (C) 2009-2011 the libgit2 contributors
|
|
*
|
|
* 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_repository_h__
|
|
#define INCLUDE_git_repository_h__
|
|
|
|
#include "common.h"
|
|
#include "types.h"
|
|
#include "oid.h"
|
|
|
|
/**
|
|
* @file git2/repository.h
|
|
* @brief Git repository management routines
|
|
* @defgroup git_repository Git repository management routines
|
|
* @ingroup Git
|
|
* @{
|
|
*/
|
|
GIT_BEGIN_DECL
|
|
|
|
/**
|
|
* Open a git repository.
|
|
*
|
|
* The 'path' argument must point to an existing git repository
|
|
* folder, e.g.
|
|
*
|
|
* /path/to/my_repo/.git/ (normal repository)
|
|
* objects/
|
|
* index
|
|
* HEAD
|
|
*
|
|
* /path/to/bare_repo/ (bare repository)
|
|
* objects/
|
|
* index
|
|
* HEAD
|
|
*
|
|
* The method will automatically detect if 'path' is a normal
|
|
* or bare repository or fail is 'path' is neither.
|
|
*
|
|
* @param repository pointer to the repo which will be opened
|
|
* @param path the path to the repository
|
|
* @return GIT_SUCCESS or an error code
|
|
*/
|
|
GIT_EXTERN(int) git_repository_open(git_repository **repository, const char *path);
|
|
|
|
|
|
/**
|
|
* Open a git repository by manually specifying all its paths
|
|
*
|
|
* @param repository pointer to the repo which will be opened
|
|
*
|
|
* @param git_dir The full path to the repository folder
|
|
* e.g. a '.git' folder for live repos, any folder for bare
|
|
* Equivalent to $GIT_DIR.
|
|
* Cannot be NULL.
|
|
*
|
|
* @param git_object_directory The full path to the ODB folder.
|
|
* the folder where all the loose and packed objects are stored
|
|
* Equivalent to $GIT_OBJECT_DIRECTORY.
|
|
* If NULL, "$GIT_DIR/objects/" is assumed.
|
|
*
|
|
* @param git_index_file The full path to the index (dircache) file
|
|
* Equivalent to $GIT_INDEX_FILE.
|
|
* If NULL, "$GIT_DIR/index" is assumed.
|
|
*
|
|
* @param git_work_tree The full path to the working tree of the repository,
|
|
* if the repository is not bare.
|
|
* Equivalent to $GIT_WORK_TREE.
|
|
* If NULL, the repository is assumed to be bare.
|
|
*
|
|
* @return GIT_SUCCESS or an error code
|
|
*/
|
|
GIT_EXTERN(int) git_repository_open2(git_repository **repository,
|
|
const char *git_dir,
|
|
const char *git_object_directory,
|
|
const char *git_index_file,
|
|
const char *git_work_tree);
|
|
|
|
|
|
/**
|
|
* Open a git repository by manually specifying its paths and
|
|
* the object database it will use.
|
|
*
|
|
* @param repository pointer to the repo which will be opened
|
|
*
|
|
* @param git_dir The full path to the repository folder
|
|
* e.g. a '.git' folder for live repos, any folder for bare
|
|
* Equivalent to $GIT_DIR.
|
|
* Cannot be NULL.
|
|
*
|
|
* @param object_database A pointer to a git_odb created & initialized
|
|
* by the user (e.g. with custom backends). This object database
|
|
* will be owned by the repository and will be automatically free'd.
|
|
* It should not be manually free'd by the user, or this
|
|
* git_repository object will become invalid.
|
|
*
|
|
* @param git_index_file The full path to the index (dircache) file
|
|
* Equivalent to $GIT_INDEX_FILE.
|
|
* If NULL, "$GIT_DIR/index" is assumed.
|
|
*
|
|
* @param git_work_tree The full path to the working tree of the repository,
|
|
* if the repository is not bare.
|
|
* Equivalent to $GIT_WORK_TREE.
|
|
* If NULL, the repository is assumed to be bare.
|
|
*
|
|
* @return GIT_SUCCESS or an error code
|
|
*/
|
|
|
|
GIT_EXTERN(int) git_repository_open3(git_repository **repository,
|
|
const char *git_dir,
|
|
git_odb *object_database,
|
|
const char *git_index_file,
|
|
const char *git_work_tree);
|
|
|
|
/**
|
|
* Look for a git repository and copy its path in the given buffer. The lookup start
|
|
* from base_path and walk across parent directories if nothing has been found. The
|
|
* lookup ends when the first repository is found, or when reaching a directory
|
|
* referenced in ceiling_dirs or when the filesystem changes (in case across_fs
|
|
* is true).
|
|
*
|
|
* The method will automatically detect if the repository is bare (if there is
|
|
* a repository).
|
|
*
|
|
* @param repository_path The user allocated buffer which will contain the found path.
|
|
*
|
|
* @param size repository_path size
|
|
*
|
|
* @param start_path The base path where the lookup starts.
|
|
*
|
|
* @param across_fs If true, then the lookup will not stop when a filesystem device change
|
|
* is detected while exploring parent directories.
|
|
*
|
|
* @param ceiling_dirs A GIT_PATH_LIST_SEPARATOR separated list of absolute symbolic link
|
|
* free paths. The lookup will stop when any of this paths is reached. Note that the
|
|
* lookup always performs on start_path no matter start_path appears in ceiling_dirs
|
|
* ceiling_dirs might be NULL (which is equivalent to an empty string)
|
|
*
|
|
* @return GIT_SUCCESS or an error code
|
|
*/
|
|
GIT_EXTERN(int) git_repository_discover(char *repository_path, size_t size, const char *start_path, int across_fs, const char *ceiling_dirs);
|
|
|
|
/**
|
|
* Get the object database behind a Git repository
|
|
*
|
|
* @param repo a repository object
|
|
* @return a pointer to the object db
|
|
*/
|
|
GIT_EXTERN(git_odb *) git_repository_database(git_repository *repo);
|
|
|
|
/**
|
|
* Open the Index file of a Git repository
|
|
*
|
|
* This returns a new and unique `git_index` object representing the
|
|
* active index for the repository.
|
|
*
|
|
* This method may be called more than once (e.g. on different threads).
|
|
*
|
|
* Each returned `git_index` object is independent and suffers no race
|
|
* conditions: synchronization is done at the FS level.
|
|
*
|
|
* Each returned `git_index` object must be manually freed by the user,
|
|
* using `git_index_free`.
|
|
*
|
|
* @param index Pointer where to store the index
|
|
* @param repo a repository object
|
|
* @return GIT_SUCCESS or an error code
|
|
*/
|
|
GIT_EXTERN(int) git_repository_index(git_index **index, git_repository *repo);
|
|
|
|
/**
|
|
* Free a previously allocated repository
|
|
*
|
|
* Note that after a repository is free'd, all the objects it has spawned
|
|
* will still exist until they are manually closed by the user
|
|
* with `git_object_close`, but accessing any of the attributes of
|
|
* an object without a backing repository will result in undefined
|
|
* behavior
|
|
*
|
|
* @param repo repository handle to close. If NULL nothing occurs.
|
|
*/
|
|
GIT_EXTERN(void) git_repository_free(git_repository *repo);
|
|
|
|
/**
|
|
* Creates a new Git repository in the given folder.
|
|
*
|
|
* TODO:
|
|
* - Reinit the repository
|
|
* - Create config files
|
|
*
|
|
* @param repo_out pointer to the repo which will be created or reinitialized
|
|
* @param path the path to the repository
|
|
* @param is_bare if true, a Git repository without a working directory is created
|
|
* at the pointed path. If false, provided path will be considered as the working
|
|
* directory into which the .git directory will be created.
|
|
*
|
|
* @return GIT_SUCCESS or an error code
|
|
*/
|
|
GIT_EXTERN(int) git_repository_init(git_repository **repo_out, const char *path, unsigned is_bare);
|
|
|
|
/**
|
|
* Retrieve and resolve the reference pointed at by HEAD.
|
|
*
|
|
* @param head_out pointer to the reference which will be retrieved
|
|
* @param repo a repository object
|
|
*
|
|
* @return 0 on success; error code otherwise
|
|
*/
|
|
GIT_EXTERN(int) git_repository_head(git_reference **head_out, git_repository *repo);
|
|
|
|
/**
|
|
* Check if a repository's HEAD is detached
|
|
*
|
|
* A repository's HEAD is detached when it points directly to a commit
|
|
* instead of a branch.
|
|
*
|
|
* @param repo Repo to test
|
|
* @return 1 if HEAD is detached, 0 if i'ts not; error code if there
|
|
* was an error.
|
|
*/
|
|
GIT_EXTERN(int) git_repository_head_detached(git_repository *repo);
|
|
|
|
/**
|
|
* Check if the current branch is an orphan
|
|
*
|
|
* An orphan branch is one named from HEAD but which doesn't exist in
|
|
* the refs namespace, because it doesn't have any commit to point to.
|
|
*
|
|
* @param repo Repo to test
|
|
* @return 1 if the current branch is an orphan, 0 if it's not; error
|
|
* code if therewas an error
|
|
*/
|
|
GIT_EXTERN(int) git_repository_head_orphan(git_repository *repo);
|
|
|
|
/**
|
|
* Check if a repository is empty
|
|
*
|
|
* An empty repository has just been initialized and contains
|
|
* no commits.
|
|
*
|
|
* @param repo Repo to test
|
|
* @return 1 if the repository is empty, 0 if it isn't, error code
|
|
* if the repository is corrupted
|
|
*/
|
|
GIT_EXTERN(int) git_repository_is_empty(git_repository *repo);
|
|
|
|
/**
|
|
* Internal path identifiers for a repository
|
|
*/
|
|
typedef enum {
|
|
GIT_REPO_PATH,
|
|
GIT_REPO_PATH_INDEX,
|
|
GIT_REPO_PATH_ODB,
|
|
GIT_REPO_PATH_WORKDIR
|
|
} git_repository_pathid;
|
|
|
|
/**
|
|
* Get one of the paths to the repository
|
|
*
|
|
* Possible values for `id`:
|
|
*
|
|
* GIT_REPO_PATH: return the path to the repository
|
|
* GIT_REPO_PATH_INDEX: return the path to the index
|
|
* GIT_REPO_PATH_ODB: return the path to the ODB
|
|
* GIT_REPO_PATH_WORKDIR: return the path to the working
|
|
* directory
|
|
*
|
|
* @param repo a repository object
|
|
* @param id The ID of the path to return
|
|
* @return absolute path of the requested id
|
|
*/
|
|
GIT_EXTERN(const char *) git_repository_path(git_repository *repo, git_repository_pathid id);
|
|
|
|
/**
|
|
* Check if a repository is bare
|
|
*
|
|
* @param repo Repo to test
|
|
* @return 1 if the repository is empty, 0 otherwise.
|
|
*/
|
|
GIT_EXTERN(int) git_repository_is_bare(git_repository *repo);
|
|
|
|
/**
|
|
* Retrieve the relevant configuration for a repository
|
|
*
|
|
* By default he returned `git_config` instance contains a single
|
|
* configuration file, the `.gitconfig' file that may be found
|
|
* inside the repository.
|
|
*
|
|
* If the `user_config_path` variable is not NULL, the given config
|
|
* file will be also included in the configuration set. On most UNIX
|
|
* systems, this file may be found on `$HOME/.gitconfig`.
|
|
*
|
|
* If the `system_config_path` variable is not NULL, the given config
|
|
* file will be also included in the configuration set. On most UNIX
|
|
* systems, this file may be found on `$PREFIX/etc/gitconfig`.
|
|
*
|
|
* The resulting `git_config` instance will query the files in the following
|
|
* order:
|
|
*
|
|
* - Repository configuration file
|
|
* - User configuration file
|
|
* - System configuration file
|
|
*
|
|
* The method will fail if any of the passed config files cannot be
|
|
* found or accessed.
|
|
*
|
|
* The returned `git_config` instance is owned by the caller and must
|
|
* be manually free'd once it's no longer on use.
|
|
*
|
|
* @param out the repository's configuration
|
|
* @param repo the repository for which to get the config
|
|
* @param user_config_path Path to the user config file
|
|
* @param system_config_path Path to the system-wide config file
|
|
*/
|
|
GIT_EXTERN(int) git_repository_config(git_config **out,
|
|
git_repository *repo,
|
|
const char *user_config_path,
|
|
const char *system_config_path);
|
|
|
|
/** @} */
|
|
GIT_END_DECL
|
|
#endif
|