include/git2/sys/repository.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_sys_git_repository_h__
   8 #define INCLUDE_sys_git_repository_h__
   9
  10 #include "git2/common.h"
  11 #include "git2/types.h"
  12
  13 /**
  14  * @file git2/sys/repository.h
  15  * @brief Git repository custom implementation routines
  16  * @defgroup git_backend Git custom backend APIs
  17  * @ingroup Git
  18  * @{
  19  */
  20 GIT_BEGIN_DECL
  21
  22 /**
  23  * Create a new repository with neither backends nor config object
  24  *
  25  * Note that this is only useful if you wish to associate the repository
  26  * with a non-filesystem-backed object database and config store.
  27  *
  28  * Caveats: since this repository has no physical location, some systems
  29  * can fail to function properly: locations under $GIT_DIR, $GIT_COMMON_DIR,
  30  * or $GIT_INFO_DIR are impacted.
  31  *
  32  * @param out The blank repository
  33  * @return 0 on success, or an error code
  34  */
  35 GIT_EXTERN(int) git_repository_new(git_repository **out);
  36
  37 /**
  38  * Reset all the internal state in a repository.
  39  *
  40  * This will free all the mapped memory and internal objects
  41  * of the repository and leave it in a "blank" state.
  42  *
  43  * There's no need to call this function directly unless you're
  44  * trying to aggressively cleanup the repo before its
  45  * deallocation. `git_repository_free` already performs this operation
  46  * before deallocating the repo.
  47  *
  48  * @param repo The repository to clean up
  49  * @return 0 on success, or an error code
  50  */
  51 GIT_EXTERN(int) git_repository__cleanup(git_repository *repo);
  52
  53 /**
  54  * Update the filesystem config settings for an open repository
  55  *
  56  * When a repository is initialized, config values are set based on the
  57  * properties of the filesystem that the repository is on, such as
  58  * "core.ignorecase", "core.filemode", "core.symlinks", etc.  If the
  59  * repository is moved to a new filesystem, these properties may no
  60  * longer be correct and API calls may not behave as expected.  This
  61  * call reruns the phase of repository initialization that sets those
  62  * properties to compensate for the current filesystem of the repo.
  63  *
  64  * @param repo A repository object
  65  * @param recurse_submodules Should submodules be updated recursively
  66  * @return 0 on success, < 0 on error
  67  */
  68 GIT_EXTERN(int) git_repository_reinit_filesystem(
  69         git_repository *repo,
  70         int recurse_submodules);
  71
  72 /**
  73  * Set the configuration file for this repository
  74  *
  75  * This configuration file will be used for all configuration
  76  * queries involving this repository.
  77  *
  78  * The repository will keep a reference to the config file;
  79  * the user must still free the config after setting it
  80  * to the repository, or it will leak.
  81  *
  82  * @param repo A repository object
  83  * @param config A Config object
  84  * @return 0 on success, or an error code
  85  */
  86 GIT_EXTERN(int) git_repository_set_config(git_repository *repo, git_config *config);
  87
  88 /**
  89  * Set the Object Database for this repository
  90  *
  91  * The ODB will be used for all object-related operations
  92  * involving this repository.
  93  *
  94  * The repository will keep a reference to the ODB; the user
  95  * must still free the ODB object after setting it to the
  96  * repository, or it will leak.
  97  *
  98  * @param repo A repository object
  99  * @param odb An ODB object
 100  * @return 0 on success, or an error code
 101  */
 102 GIT_EXTERN(int) git_repository_set_odb(git_repository *repo, git_odb *odb);
 103
 104 /**
 105  * Set the Reference Database Backend for this repository
 106  *
 107  * The refdb will be used for all reference related operations
 108  * involving this repository.
 109  *
 110  * The repository will keep a reference to the refdb; the user
 111  * must still free the refdb object after setting it to the
 112  * repository, or it will leak.
 113  *
 114  * @param repo A repository object
 115  * @param refdb An refdb object
 116  * @return 0 on success, or an error code
 117  */
 118 GIT_EXTERN(int) git_repository_set_refdb(git_repository *repo, git_refdb *refdb);
 119
 120 /**
 121  * Set the index file for this repository
 122  *
 123  * This index will be used for all index-related operations
 124  * involving this repository.
 125  *
 126  * The repository will keep a reference to the index file;
 127  * the user must still free the index after setting it
 128  * to the repository, or it will leak.
 129  *
 130  * @param repo A repository object
 131  * @param index An index object
 132  * @return 0 on success, or an error code
 133  */
 134 GIT_EXTERN(int) git_repository_set_index(git_repository *repo, git_index *index);
 135
 136 /**
 137  * Set a repository to be bare.
 138  *
 139  * Clear the working directory and set core.bare to true.  You may also
 140  * want to call `git_repository_set_index(repo, NULL)` since a bare repo
 141  * typically does not have an index, but this function will not do that
 142  * for you.
 143  *
 144  * @param repo Repo to make bare
 145  * @return 0 on success, <0 on failure
 146  */
 147 GIT_EXTERN(int) git_repository_set_bare(git_repository *repo);
 148
 149 /**
 150  * Load and cache all submodules.
 151  *
 152  * Because the `.gitmodules` file is unstructured, loading submodules is an
 153  * O(N) operation.  Any operation (such as `git_rebase_init`) that requires
 154  * accessing all submodules is O(N^2) in the number of submodules, if it
 155  * has to look each one up individually.  This function loads all submodules
 156  * and caches them so that subsequent calls to `git_submodule_lookup` are O(1).
 157  *
 158  * @param repo the repository whose submodules will be cached.
 159  */
 160 GIT_EXTERN(int) git_repository_submodule_cache_all(
 161         git_repository *repo);
 162
 163 /**
 164  * Clear the submodule cache.
 165  *
 166  * Clear the submodule cache populated by `git_repository_submodule_cache_all`.
 167  * If there is no cache, do nothing.
 168  *
 169  * The cache incorporates data from the repository's configuration, as well
 170  * as the state of the working tree, the index, and HEAD.  So any time any
 171  * of these has changed, the cache might become invalid.
 172  *
 173  * @param repo the repository whose submodule cache will be cleared
 174  */
 175 GIT_EXTERN(int) git_repository_submodule_cache_clear(
 176         git_repository *repo);
 177
 178 /** @} */
 179 GIT_END_DECL
 180 #endif