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