include/git2/repository.h

   1 /*
   2  * This file is free software; you can redistribute it and/or modify
   3  * it under the terms of the GNU General Public License, version 2,
   4  * as published by the Free Software Foundation.
   5  *
   6  * In addition to the permissions in the GNU General Public License,
   7  * the authors give you unlimited permission to link the compiled
   8  * version of this file into combinations with other programs,
   9  * and to distribute those combinations without any restriction
  10  * coming from the use of this file.  (The General Public License
  11  * restrictions do apply in other respects; for example, they cover
  12  * modification of the file, and distribution when not linked into
  13  * a combined executable.)
  14  *
  15  * This file is distributed in the hope that it will be useful, but
  16  * WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License
  21  * along with this program; see the file COPYING.  If not, write to
  22  * the Free Software Foundation, 51 Franklin Street, Fifth Floor,
  23  * Boston, MA 02110-1301, USA.
  24  */
  25 #ifndef INCLUDE_git_repository_h__
  26 #define INCLUDE_git_repository_h__
  27
  28 #include "common.h"
  29 #include "types.h"
  30 #include "oid.h"
  31
  32 /**
  33  * @file git2/repository.h
  34  * @brief Git repository management routines
  35  * @defgroup git_repository Git repository management routines
  36  * @ingroup Git
  37  * @{
  38  */
  39 GIT_BEGIN_DECL
  40
  41 /**
  42  * Open a git repository.
  43  *
  44  * The 'path' argument must point to an existing git repository
  45  * folder, e.g.
  46  *
  47  *              /path/to/my_repo/.git/  (normal repository)
  48  *                                                      objects/
  49  *                                                      index
  50  *                                                      HEAD
  51  *
  52  *              /path/to/bare_repo/             (bare repository)
  53  *                                              objects/
  54  *                                              index
  55  *                                              HEAD
  56  *
  57  *      The method will automatically detect if 'path' is a normal
  58  *      or bare repository or fail is 'path' is neither.
  59  *
  60  * @param repository pointer to the repo which will be opened
  61  * @param path the path to the repository
  62  * @return 0 on success; error code otherwise
  63  */
  64 GIT_EXTERN(int) git_repository_open(git_repository **repository, const char *path);
  65
  66
  67 /**
  68  * Open a git repository by manually specifying all its paths
  69  *
  70  * @param repository pointer to the repo which will be opened
  71  *
  72  * @param git_dir The full path to the repository folder
  73  *              e.g. a '.git' folder for live repos, any folder for bare
  74  *              Equivalent to $GIT_DIR.
  75  *              Cannot be NULL.
  76  *
  77  * @param git_object_directory The full path to the ODB folder.
  78  *              the folder where all the loose and packed objects are stored
  79  *              Equivalent to $GIT_OBJECT_DIRECTORY.
  80  *              If NULL, "$GIT_DIR/objects/" is assumed.
  81  *
  82  * @param git_index_file The full path to the index (dircache) file
  83  *              Equivalent to $GIT_INDEX_FILE.
  84  *              If NULL, "$GIT_DIR/index" is assumed.
  85  *
  86  * @param git_work_tree The full path to the working tree of the repository,
  87  *              if the repository is not bare.
  88  *              Equivalent to $GIT_WORK_TREE.
  89  *              If NULL, the repository is assumed to be bare.
  90  *
  91  * @return 0 on success; error code otherwise
  92  */
  93 GIT_EXTERN(int) git_repository_open2(git_repository **repository,
  94                 const char *git_dir,
  95                 const char *git_object_directory,
  96                 const char *git_index_file,
  97                 const char *git_work_tree);
  98
  99
 100 /**
 101  * Open a git repository by manually specifying its paths and
 102  * the object database it will use.
 103  *
 104  * @param repository pointer to the repo which will be opened
 105  *
 106  * @param git_dir The full path to the repository folder
 107  *              e.g. a '.git' folder for live repos, any folder for bare
 108  *              Equivalent to $GIT_DIR.
 109  *              Cannot be NULL.
 110  *
 111  * @param object_database A pointer to a git_odb created & initialized
 112  *              by the user (e.g. with custom backends). This object database
 113  *              will be owned by the repository and will be automatically free'd.
 114  *              It should not be manually free'd by the user, or this
 115  *              git_repository object will become invalid.
 116  *
 117  * @param git_index_file The full path to the index (dircache) file
 118  *              Equivalent to $GIT_INDEX_FILE.
 119  *              If NULL, "$GIT_DIR/index" is assumed.
 120  *
 121  * @param git_work_tree The full path to the working tree of the repository,
 122  *              if the repository is not bare.
 123  *              Equivalent to $GIT_WORK_TREE.
 124  *              If NULL, the repository is assumed to be bare.
 125  *
 126  * @return 0 on success; error code otherwise
 127  */
 128
 129 GIT_EXTERN(int) git_repository_open3(git_repository **repository,
 130                 const char *git_dir,
 131                 git_odb *object_database,
 132                 const char *git_index_file,
 133                 const char *git_work_tree);
 134
 135 /**
 136  * Get the object database behind a Git repository
 137  *
 138  * @param repo a repository object
 139  * @return a pointer to the object db
 140  */
 141 GIT_EXTERN(git_odb *) git_repository_database(git_repository *repo);
 142
 143 /**
 144  * Get the Index file of a Git repository
 145  *
 146  * This is a cheap operation; the index is only opened on the first call,
 147  * and subsequent calls only retrieve the previous pointer.
 148  *
 149  * @param index Pointer where to store the index
 150  * @param repo a repository object
 151  * @return 0 on success; error code if the index could not be opened
 152  */
 153 GIT_EXTERN(int) git_repository_index(git_index **index, git_repository *repo);
 154
 155 /**
 156  * Free a previously allocated repository
 157  *
 158  * Note that after a repository is free'd, all the objects it has spawned
 159  * will still exist until they are manually closed by the user
 160  * with `git_object_close`, but accessing any of the attributes of
 161  * an object without a backing repository will result in undefined
 162  * behavior
 163  *
 164  * @param repo repository handle to close. If NULL nothing occurs.
 165  */
 166 GIT_EXTERN(void) git_repository_free(git_repository *repo);
 167
 168 /**
 169  * Creates a new Git repository in the given folder.
 170  *
 171  * TODO:
 172  *      - Reinit the repository
 173  *      - Create config files
 174  *
 175  * @param repo_out pointer to the repo which will be created or reinitialized
 176  * @param path the path to the repository
 177  * @param is_bare if true, a Git repository without a working directory is created
 178  *              at the pointed path. If false, provided path will be considered as the working
 179  *              directory into which the .git directory will be created.
 180  *
 181  * @return 0 on success; error code otherwise
 182  */
 183 GIT_EXTERN(int) git_repository_init(git_repository **repo_out, const char *path, unsigned is_bare);
 184
 185 /**
 186  * Check if a repository is empty
 187  *
 188  * An empty repository has just been initialized and contains
 189  * no commits.
 190  *
 191  * @param repo Repo to test
 192  * @return 1 if the repository is empty, 0 if it isn't, error code
 193  * if the repository is corrupted
 194  */
 195 GIT_EXTERN(int) git_repository_is_empty(git_repository *repo);
 196
 197 /** @} */
 198 GIT_END_DECL
 199 #endif