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