]>
Commit | Line | Data |
---|---|---|
f5918330 | 1 | /* |
5e0de328 | 2 | * Copyright (C) 2009-2012 the libgit2 contributors |
f5918330 | 3 | * |
bb742ede VM |
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. | |
f5918330 | 6 | */ |
3315782c VM |
7 | #ifndef INCLUDE_git_repository_h__ |
8 | #define INCLUDE_git_repository_h__ | |
9 | ||
10 | #include "common.h" | |
d12299fe VM |
11 | #include "types.h" |
12 | #include "oid.h" | |
3315782c VM |
13 | |
14 | /** | |
f5918330 | 15 | * @file git2/repository.h |
d12299fe VM |
16 | * @brief Git repository management routines |
17 | * @defgroup git_repository Git repository management routines | |
3315782c VM |
18 | * @ingroup Git |
19 | * @{ | |
20 | */ | |
21 | GIT_BEGIN_DECL | |
22 | ||
23 | /** | |
6fd195d7 | 24 | * Open a git repository. |
3315782c | 25 | * |
9462c471 VM |
26 | * The 'path' argument must point to either a git repository |
27 | * folder, or an existing work dir. | |
3315782c | 28 | * |
9462c471 VM |
29 | * The method will automatically detect if 'path' is a normal |
30 | * or bare repository or fail is 'path' is neither. | |
6fd195d7 | 31 | * |
1795f879 | 32 | * @param repository pointer to the repo which will be opened |
6fd195d7 | 33 | * @param path the path to the repository |
e172cf08 | 34 | * @return 0 or an error code |
3315782c | 35 | */ |
1795f879 | 36 | GIT_EXTERN(int) git_repository_open(git_repository **repository, const char *path); |
3315782c | 37 | |
6782245e CMN |
38 | /** |
39 | * Create a "fake" repository to wrap an object database | |
40 | * | |
41 | * Create a repository object to wrap an object database to be used | |
42 | * with the API when all you have is an object database. This doesn't | |
43 | * have any paths associated with it, so use with care. | |
44 | * | |
45 | * @param repository pointer to the repo | |
46 | * @param odb the object database to wrap | |
47 | * @return 0 or an error code | |
48 | */ | |
49 | GIT_EXTERN(int) git_repository_wrap_odb(git_repository **repository, git_odb *odb); | |
50 | ||
fd0574e5 | 51 | /** |
9462c471 VM |
52 | * Look for a git repository and copy its path in the given buffer. |
53 | * The lookup start from base_path and walk across parent directories | |
54 | * if nothing has been found. The lookup ends when the first repository | |
55 | * is found, or when reaching a directory referenced in ceiling_dirs | |
56 | * or when the filesystem changes (in case across_fs is true). | |
fd0574e5 | 57 | * |
9462c471 VM |
58 | * The method will automatically detect if the repository is bare |
59 | * (if there is a repository). | |
fd0574e5 | 60 | * |
9462c471 VM |
61 | * @param repository_path The user allocated buffer which will |
62 | * contain the found path. | |
fd0574e5 RG |
63 | * |
64 | * @param size repository_path size | |
65 | * | |
66 | * @param start_path The base path where the lookup starts. | |
67 | * | |
9462c471 VM |
68 | * @param across_fs If true, then the lookup will not stop when a |
69 | * filesystem device change is detected while exploring parent directories. | |
fd0574e5 | 70 | * |
9462c471 VM |
71 | * @param ceiling_dirs A GIT_PATH_LIST_SEPARATOR separated list of |
72 | * absolute symbolic link free paths. The lookup will stop when any | |
73 | * of this paths is reached. Note that the lookup always performs on | |
74 | * start_path no matter start_path appears in ceiling_dirs ceiling_dirs | |
75 | * might be NULL (which is equivalent to an empty string) | |
fd0574e5 | 76 | * |
e172cf08 | 77 | * @return 0 or an error code |
fd0574e5 | 78 | */ |
9462c471 VM |
79 | GIT_EXTERN(int) git_repository_discover( |
80 | char *repository_path, | |
81 | size_t size, | |
82 | const char *start_path, | |
83 | int across_fs, | |
84 | const char *ceiling_dirs); | |
6fd195d7 | 85 | |
7784bcbb RB |
86 | enum { |
87 | GIT_REPOSITORY_OPEN_NO_SEARCH = (1 << 0), | |
88 | GIT_REPOSITORY_OPEN_CROSS_FS = (1 << 1), | |
89 | }; | |
90 | ||
91 | /** | |
92 | * Find and open a repository with extended controls. | |
93 | */ | |
94 | GIT_EXTERN(int) git_repository_open_ext( | |
95 | git_repository **repo, | |
96 | const char *start_path, | |
97 | uint32_t flags, | |
98 | const char *ceiling_dirs); | |
99 | ||
3315782c VM |
100 | /** |
101 | * Free a previously allocated repository | |
6b2a1941 | 102 | * |
f0d08b7c VM |
103 | * Note that after a repository is free'd, all the objects it has spawned |
104 | * will still exist until they are manually closed by the user | |
45e79e37 | 105 | * with `git_object_free`, but accessing any of the attributes of |
f0d08b7c VM |
106 | * an object without a backing repository will result in undefined |
107 | * behavior | |
108 | * | |
3315782c VM |
109 | * @param repo repository handle to close. If NULL nothing occurs. |
110 | */ | |
111 | GIT_EXTERN(void) git_repository_free(git_repository *repo); | |
112 | ||
e1f8cad0 | 113 | /** |
40c44d2f | 114 | * Creates a new Git repository in the given folder. |
e1f8cad0 | 115 | * |
40c44d2f VM |
116 | * TODO: |
117 | * - Reinit the repository | |
e1f8cad0 | 118 | * |
119 | * @param repo_out pointer to the repo which will be created or reinitialized | |
120 | * @param path the path to the repository | |
932d1baf KS |
121 | * @param is_bare if true, a Git repository without a working directory is created |
122 | * at the pointed path. If false, provided path will be considered as the working | |
40c44d2f VM |
123 | * directory into which the .git directory will be created. |
124 | * | |
e172cf08 | 125 | * @return 0 or an error code |
e1f8cad0 | 126 | */ |
40c44d2f | 127 | GIT_EXTERN(int) git_repository_init(git_repository **repo_out, const char *path, unsigned is_bare); |
4b8e27c8 | 128 | |
3601c4bf | 129 | /** |
130 | * Retrieve and resolve the reference pointed at by HEAD. | |
131 | * | |
132 | * @param head_out pointer to the reference which will be retrieved | |
133 | * @param repo a repository object | |
134 | * | |
135 | * @return 0 on success; error code otherwise | |
136 | */ | |
137 | GIT_EXTERN(int) git_repository_head(git_reference **head_out, git_repository *repo); | |
138 | ||
35502d2e CMN |
139 | /** |
140 | * Check if a repository's HEAD is detached | |
141 | * | |
142 | * A repository's HEAD is detached when it points directly to a commit | |
143 | * instead of a branch. | |
144 | * | |
145 | * @param repo Repo to test | |
d73c94b2 | 146 | * @return 1 if HEAD is detached, 0 if it's not; error code if there |
35502d2e CMN |
147 | * was an error. |
148 | */ | |
408d733b | 149 | GIT_EXTERN(int) git_repository_head_detached(git_repository *repo); |
35502d2e CMN |
150 | |
151 | /** | |
152 | * Check if the current branch is an orphan | |
153 | * | |
154 | * An orphan branch is one named from HEAD but which doesn't exist in | |
155 | * the refs namespace, because it doesn't have any commit to point to. | |
156 | * | |
157 | * @param repo Repo to test | |
158 | * @return 1 if the current branch is an orphan, 0 if it's not; error | |
d73c94b2 | 159 | * code if there was an error |
35502d2e | 160 | */ |
408d733b | 161 | GIT_EXTERN(int) git_repository_head_orphan(git_repository *repo); |
35502d2e | 162 | |
41233c40 VM |
163 | /** |
164 | * Check if a repository is empty | |
165 | * | |
166 | * An empty repository has just been initialized and contains | |
167 | * no commits. | |
168 | * | |
169 | * @param repo Repo to test | |
170 | * @return 1 if the repository is empty, 0 if it isn't, error code | |
171 | * if the repository is corrupted | |
172 | */ | |
173 | GIT_EXTERN(int) git_repository_is_empty(git_repository *repo); | |
174 | ||
6632c155 VM |
175 | /** |
176 | * Get the path of this repository | |
177 | * | |
178 | * This is the path of the `.git` folder for normal repositories, | |
179 | * or of the repository itself for bare repositories. | |
180 | * | |
181 | * @param repo A repository object | |
182 | * @return the path to the repository | |
183 | */ | |
9462c471 | 184 | GIT_EXTERN(const char *) git_repository_path(git_repository *repo); |
6632c155 VM |
185 | |
186 | /** | |
187 | * Get the path of the working directory for this repository | |
188 | * | |
189 | * If the repository is bare, this function will always return | |
190 | * NULL. | |
191 | * | |
192 | * @param repo A repository object | |
193 | * @return the path to the working dir, if it exists | |
194 | */ | |
9462c471 | 195 | GIT_EXTERN(const char *) git_repository_workdir(git_repository *repo); |
6632c155 VM |
196 | |
197 | /** | |
198 | * Set the path to the working directory for this repository | |
199 | * | |
200 | * The working directory doesn't need to be the same one | |
201 | * that contains the `.git` folder for this repository. | |
202 | * | |
203 | * If this repository is bare, setting its working directory | |
204 | * will turn it into a normal repository, capable of performing | |
205 | * all the common workdir operations (checkout, status, index | |
206 | * manipulation, etc). | |
207 | * | |
208 | * @param repo A repository object | |
209 | * @param workdir The path to a working directory | |
991a56c7 RB |
210 | * @param update_gitlink Create/update gitlink in workdir and set config |
211 | * "core.worktree" (if workdir is not the parent of the .git directory) | |
e172cf08 | 212 | * @return 0, or an error code |
6632c155 | 213 | */ |
991a56c7 RB |
214 | GIT_EXTERN(int) git_repository_set_workdir( |
215 | git_repository *repo, const char *workdir, int update_gitlink); | |
4a34b3a9 | 216 | |
fa9bcd81 | 217 | /** |
218 | * Check if a repository is bare | |
219 | * | |
220 | * @param repo Repo to test | |
28ba94ce | 221 | * @return 1 if the repository is bare, 0 otherwise. |
fa9bcd81 | 222 | */ |
223 | GIT_EXTERN(int) git_repository_is_bare(git_repository *repo); | |
224 | ||
6632c155 VM |
225 | /** |
226 | * Get the configuration file for this repository. | |
227 | * | |
228 | * If a configuration file has not been set, the default | |
229 | * config set for the repository will be returned, including | |
230 | * global and system configurations (if they are available). | |
231 | * | |
232 | * The configuration file must be freed once it's no longer | |
233 | * being used by the user. | |
234 | * | |
235 | * @param out Pointer to store the loaded config file | |
236 | * @param repo A repository object | |
e172cf08 | 237 | * @return 0, or an error code |
6632c155 | 238 | */ |
9462c471 | 239 | GIT_EXTERN(int) git_repository_config(git_config **out, git_repository *repo); |
6632c155 VM |
240 | |
241 | /** | |
242 | * Set the configuration file for this repository | |
243 | * | |
244 | * This configuration file will be used for all configuration | |
245 | * queries involving this repository. | |
246 | * | |
247 | * The repository will keep a reference to the config file; | |
248 | * the user must still free the config after setting it | |
249 | * to the repository, or it will leak. | |
250 | * | |
251 | * @param repo A repository object | |
252 | * @param config A Config object | |
253 | */ | |
9462c471 | 254 | GIT_EXTERN(void) git_repository_set_config(git_repository *repo, git_config *config); |
40fe5fbe | 255 | |
6632c155 VM |
256 | /** |
257 | * Get the Object Database for this repository. | |
258 | * | |
259 | * If a custom ODB has not been set, the default | |
260 | * database for the repository will be returned (the one | |
261 | * located in `.git/objects`). | |
262 | * | |
263 | * The ODB must be freed once it's no longer being used by | |
264 | * the user. | |
265 | * | |
266 | * @param out Pointer to store the loaded ODB | |
267 | * @param repo A repository object | |
e172cf08 | 268 | * @return 0, or an error code |
6632c155 | 269 | */ |
9462c471 | 270 | GIT_EXTERN(int) git_repository_odb(git_odb **out, git_repository *repo); |
6632c155 VM |
271 | |
272 | /** | |
273 | * Set the Object Database for this repository | |
274 | * | |
275 | * The ODB will be used for all object-related operations | |
276 | * involving this repository. | |
277 | * | |
278 | * The repository will keep a reference to the ODB; the user | |
279 | * must still free the ODB object after setting it to the | |
280 | * repository, or it will leak. | |
281 | * | |
282 | * @param repo A repository object | |
283 | * @param odb An ODB object | |
284 | */ | |
9462c471 | 285 | GIT_EXTERN(void) git_repository_set_odb(git_repository *repo, git_odb *odb); |
b22d1479 | 286 | |
6632c155 VM |
287 | /** |
288 | * Get the Index file for this repository. | |
289 | * | |
290 | * If a custom index has not been set, the default | |
291 | * index for the repository will be returned (the one | |
292 | * located in `.git/index`). | |
293 | * | |
294 | * The index must be freed once it's no longer being used by | |
295 | * the user. | |
296 | * | |
297 | * @param out Pointer to store the loaded index | |
298 | * @param repo A repository object | |
e172cf08 | 299 | * @return 0, or an error code |
6632c155 | 300 | */ |
9462c471 | 301 | GIT_EXTERN(int) git_repository_index(git_index **out, git_repository *repo); |
6632c155 VM |
302 | |
303 | /** | |
304 | * Set the index file for this repository | |
305 | * | |
306 | * This index will be used for all index-related operations | |
307 | * involving this repository. | |
308 | * | |
309 | * The repository will keep a reference to the index file; | |
310 | * the user must still free the index after setting it | |
311 | * to the repository, or it will leak. | |
312 | * | |
313 | * @param repo A repository object | |
314 | * @param index An index object | |
315 | */ | |
9462c471 | 316 | GIT_EXTERN(void) git_repository_set_index(git_repository *repo, git_index *index); |
40fe5fbe | 317 | |
074841ec CMN |
318 | /** |
319 | * Retrive git's prepared message | |
320 | * | |
321 | * Operations such as git revert/cherry-pick/merge with the -n option | |
322 | * stop just short of creating a commit with the changes and save | |
323 | * their prepared message in .git/MERGE_MSG so the next git-commit | |
324 | * execution can present it to the user for them to amend if they | |
325 | * wish. | |
326 | * | |
327 | * Use this function to get the contents of this file. Don't forget to | |
328 | * remove the file after you create the commit. | |
329 | */ | |
330 | GIT_EXTERN(int) git_repository_message(char *buffer, size_t len, git_repository *repo); | |
331 | ||
332 | /** | |
333 | * Remove git's prepared message. | |
334 | * | |
335 | * Remove the message that `git_repository_message` retrieves. | |
336 | */ | |
337 | GIT_EXTERN(int) git_repository_message_remove(git_repository *repo); | |
338 | ||
339 | ||
3315782c VM |
340 | /** @} */ |
341 | GIT_END_DECL | |
342 | #endif |