]>
Commit | Line | Data |
---|---|---|
45f2b7a4 PS |
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_git_worktree_h__ | |
8 | #define INCLUDE_git_worktree_h__ | |
9 | ||
10 | #include "common.h" | |
2a503485 | 11 | #include "buffer.h" |
45f2b7a4 PS |
12 | #include "types.h" |
13 | #include "strarray.h" | |
14 | ||
15 | /** | |
16 | * @file git2/worktrees.h | |
17 | * @brief Git worktree related functions | |
18 | * @defgroup git_commit Git worktree related functions | |
19 | * @ingroup Git | |
20 | * @{ | |
21 | */ | |
22 | GIT_BEGIN_DECL | |
23 | ||
24 | /** | |
25 | * List names of linked working trees | |
26 | * | |
27 | * The returned list should be released with `git_strarray_free` | |
28 | * when no longer needed. | |
29 | * | |
30 | * @param out pointer to the array of working tree names | |
31 | * @param repo the repo to use when listing working trees | |
32 | * @return 0 or an error code | |
33 | */ | |
34 | GIT_EXTERN(int) git_worktree_list(git_strarray *out, git_repository *repo); | |
35 | ||
d3bc09e8 PS |
36 | /** |
37 | * Lookup a working tree by its name for a given repository | |
38 | * | |
39 | * @param out Output pointer to looked up worktree or `NULL` | |
40 | * @param repo The repository containing worktrees | |
41 | * @param name Name of the working tree to look up | |
42 | * @return 0 or an error code | |
43 | */ | |
44 | GIT_EXTERN(int) git_worktree_lookup(git_worktree **out, git_repository *repo, const char *name); | |
45 | ||
3017ba94 PS |
46 | /** |
47 | * Open a worktree of a given repository | |
48 | * | |
49 | * If a repository is not the main tree but a worktree, this | |
50 | * function will look up the worktree inside the parent | |
51 | * repository and create a new `git_worktree` structure. | |
52 | * | |
53 | * @param out Out-pointer for the newly allocated worktree | |
54 | * @param repo Repository to look up worktree for | |
55 | */ | |
56 | GIT_EXTERN(int) git_worktree_open_from_repository(git_worktree **out, git_repository *repo); | |
57 | ||
d3bc09e8 PS |
58 | /** |
59 | * Free a previously allocated worktree | |
60 | * | |
61 | * @param wt worktree handle to close. If NULL nothing occurs. | |
62 | */ | |
63 | GIT_EXTERN(void) git_worktree_free(git_worktree *wt); | |
64 | ||
372dc9ff PS |
65 | /** |
66 | * Check if worktree is valid | |
67 | * | |
68 | * A valid worktree requires both the git data structures inside | |
69 | * the linked parent repository and the linked working copy to be | |
70 | * present. | |
71 | * | |
72 | * @param wt Worktree to check | |
73 | * @return 0 when worktree is valid, error-code otherwise | |
74 | */ | |
75 | GIT_EXTERN(int) git_worktree_validate(const git_worktree *wt); | |
76 | ||
ac3d33df JK |
77 | /** |
78 | * Worktree add options structure | |
79 | * | |
80 | * Initialize with `GIT_WORKTREE_ADD_OPTIONS_INIT`. Alternatively, you can | |
22a2d3d5 | 81 | * use `git_worktree_add_options_init`. |
ac3d33df JK |
82 | * |
83 | */ | |
a7aa73a5 PS |
84 | typedef struct git_worktree_add_options { |
85 | unsigned int version; | |
8264a30f | 86 | |
f0848dd7 | 87 | int lock; /**< lock newly created worktree */ |
ac3d33df | 88 | git_reference *ref; /**< reference to use for the new worktree HEAD */ |
a7aa73a5 PS |
89 | } git_worktree_add_options; |
90 | ||
91 | #define GIT_WORKTREE_ADD_OPTIONS_VERSION 1 | |
ac3d33df | 92 | #define GIT_WORKTREE_ADD_OPTIONS_INIT {GIT_WORKTREE_ADD_OPTIONS_VERSION,0,NULL} |
a7aa73a5 PS |
93 | |
94 | /** | |
ac3d33df JK |
95 | * Initialize git_worktree_add_options structure |
96 | * | |
97 | * Initializes a `git_worktree_add_options` with default values. Equivalent to | |
98 | * creating an instance with `GIT_WORKTREE_ADD_OPTIONS_INIT`. | |
a7aa73a5 | 99 | * |
ac3d33df JK |
100 | * @param opts The `git_worktree_add_options` struct to initialize. |
101 | * @param version The struct version; pass `GIT_WORKTREE_ADD_OPTIONS_VERSION`. | |
a7aa73a5 PS |
102 | * @return Zero on success; -1 on failure. |
103 | */ | |
22a2d3d5 | 104 | GIT_EXTERN(int) git_worktree_add_options_init(git_worktree_add_options *opts, |
a7aa73a5 PS |
105 | unsigned int version); |
106 | ||
dea7488e PS |
107 | /** |
108 | * Add a new working tree | |
109 | * | |
110 | * Add a new working tree for the repository, that is create the | |
111 | * required data structures inside the repository and check out | |
112 | * the current HEAD at `path` | |
113 | * | |
114 | * @param out Output pointer containing new working tree | |
115 | * @param repo Repository to create working tree for | |
116 | * @param name Name of the working tree | |
117 | * @param path Path to create working tree at | |
a7aa73a5 | 118 | * @param opts Options to modify default behavior. May be NULL |
dea7488e PS |
119 | * @return 0 or an error code |
120 | */ | |
a7aa73a5 PS |
121 | GIT_EXTERN(int) git_worktree_add(git_worktree **out, git_repository *repo, |
122 | const char *name, const char *path, | |
123 | const git_worktree_add_options *opts); | |
dea7488e | 124 | |
04fb12ab | 125 | /** |
2a503485 PS |
126 | * Lock worktree if not already locked |
127 | * | |
128 | * Lock a worktree, optionally specifying a reason why the linked | |
129 | * working tree is being locked. | |
130 | * | |
131 | * @param wt Worktree to lock | |
132 | * @param reason Reason why the working tree is being locked | |
133 | * @return 0 on success, non-zero otherwise | |
134 | */ | |
eae0bfdc | 135 | GIT_EXTERN(int) git_worktree_lock(git_worktree *wt, const char *reason); |
2a503485 PS |
136 | |
137 | /** | |
138 | * Unlock a locked worktree | |
139 | * | |
140 | * @param wt Worktree to unlock | |
141 | * @return 0 on success, 1 if worktree was not locked, error-code | |
142 | * otherwise | |
143 | */ | |
144 | GIT_EXTERN(int) git_worktree_unlock(git_worktree *wt); | |
145 | ||
146 | /** | |
147 | * Check if worktree is locked | |
148 | * | |
149 | * A worktree may be locked if the linked working tree is stored | |
150 | * on a portable device which is not available. | |
151 | * | |
152 | * @param reason Buffer to store reason in. If NULL no reason is stored. | |
153 | * @param wt Worktree to check | |
154 | * @return 0 when the working tree not locked, a value greater | |
155 | * than zero if it is locked, less than zero if there was an | |
156 | * error | |
157 | */ | |
158 | GIT_EXTERN(int) git_worktree_is_locked(git_buf *reason, const git_worktree *wt); | |
159 | ||
ac3d33df JK |
160 | /** |
161 | * Retrieve the name of the worktree | |
162 | * | |
163 | * @param wt Worktree to get the name for | |
164 | * @return The worktree's name. The pointer returned is valid for the | |
165 | * lifetime of the git_worktree | |
166 | */ | |
167 | GIT_EXTERN(const char *) git_worktree_name(const git_worktree *wt); | |
168 | ||
169 | /** | |
170 | * Retrieve the filesystem path for the worktree | |
171 | * | |
172 | * @param wt Worktree to get the path for | |
173 | * @return The worktree's filesystem path. The pointer returned | |
174 | * is valid for the lifetime of the git_worktree. | |
175 | */ | |
176 | GIT_EXTERN(const char *) git_worktree_path(const git_worktree *wt); | |
22a2d3d5 | 177 | |
f0cfc341 PS |
178 | /** |
179 | * Flags which can be passed to git_worktree_prune to alter its | |
180 | * behavior. | |
181 | */ | |
182 | typedef enum { | |
183 | /* Prune working tree even if working tree is valid */ | |
184 | GIT_WORKTREE_PRUNE_VALID = 1u << 0, | |
185 | /* Prune working tree even if it is locked */ | |
186 | GIT_WORKTREE_PRUNE_LOCKED = 1u << 1, | |
187 | /* Prune checked out working tree */ | |
188 | GIT_WORKTREE_PRUNE_WORKING_TREE = 1u << 2, | |
189 | } git_worktree_prune_t; | |
190 | ||
ac3d33df JK |
191 | /** |
192 | * Worktree prune options structure | |
193 | * | |
194 | * Initialize with `GIT_WORKTREE_PRUNE_OPTIONS_INIT`. Alternatively, you can | |
22a2d3d5 | 195 | * use `git_worktree_prune_options_init`. |
ac3d33df JK |
196 | * |
197 | */ | |
883eeb5f PS |
198 | typedef struct git_worktree_prune_options { |
199 | unsigned int version; | |
200 | ||
201 | uint32_t flags; | |
202 | } git_worktree_prune_options; | |
203 | ||
204 | #define GIT_WORKTREE_PRUNE_OPTIONS_VERSION 1 | |
205 | #define GIT_WORKTREE_PRUNE_OPTIONS_INIT {GIT_WORKTREE_PRUNE_OPTIONS_VERSION,0} | |
206 | ||
207 | /** | |
ac3d33df JK |
208 | * Initialize git_worktree_prune_options structure |
209 | * | |
210 | * Initializes a `git_worktree_prune_options` with default values. Equivalent to | |
211 | * creating an instance with `GIT_WORKTREE_PRUNE_OPTIONS_INIT`. | |
883eeb5f | 212 | * |
ac3d33df JK |
213 | * @param opts The `git_worktree_prune_options` struct to initialize. |
214 | * @param version The struct version; pass `GIT_WORKTREE_PRUNE_OPTIONS_VERSION`. | |
883eeb5f PS |
215 | * @return Zero on success; -1 on failure. |
216 | */ | |
22a2d3d5 | 217 | GIT_EXTERN(int) git_worktree_prune_options_init( |
883eeb5f PS |
218 | git_worktree_prune_options *opts, |
219 | unsigned int version); | |
220 | ||
1ba242c9 | 221 | /** |
883eeb5f | 222 | * Is the worktree prunable with the given options? |
1ba242c9 PS |
223 | * |
224 | * A worktree is not prunable in the following scenarios: | |
225 | * | |
226 | * - the worktree is linking to a valid on-disk worktree. The | |
883eeb5f PS |
227 | * `valid` member will cause this check to be ignored. |
228 | * - the worktree is locked. The `locked` flag will cause this | |
229 | * check to be ignored. | |
1ba242c9 PS |
230 | * |
231 | * If the worktree is not valid and not locked or if the above | |
232 | * flags have been passed in, this function will return a | |
233 | * positive value. | |
234 | */ | |
883eeb5f PS |
235 | GIT_EXTERN(int) git_worktree_is_prunable(git_worktree *wt, |
236 | git_worktree_prune_options *opts); | |
1ba242c9 | 237 | |
f0cfc341 PS |
238 | /** |
239 | * Prune working tree | |
240 | * | |
241 | * Prune the working tree, that is remove the git data | |
242 | * structures on disk. The repository will only be pruned of | |
243 | * `git_worktree_is_prunable` succeeds. | |
244 | * | |
245 | * @param wt Worktree to prune | |
883eeb5f PS |
246 | * @param opts Specifies which checks to override. See |
247 | * `git_worktree_is_prunable`. May be NULL | |
f0cfc341 PS |
248 | * @return 0 or an error code |
249 | */ | |
883eeb5f PS |
250 | GIT_EXTERN(int) git_worktree_prune(git_worktree *wt, |
251 | git_worktree_prune_options *opts); | |
f0cfc341 | 252 | |
45f2b7a4 PS |
253 | /** @} */ |
254 | GIT_END_DECL | |
255 | #endif |