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