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" 11 #include "buffer.h" 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 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 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 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 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 77 /** 78 * Worktree add options structure 79 * 80 * Initialize with `GIT_WORKTREE_ADD_OPTIONS_INIT`. Alternatively, you can 81 * use `git_worktree_add_options_init`. 82 * 83 */ 84 typedef struct git_worktree_add_options { 85 unsigned int version; 86 87 int lock; /**< lock newly created worktree */ 88 git_reference *ref; /**< reference to use for the new worktree HEAD */ 89 } git_worktree_add_options; 90 91 #define GIT_WORKTREE_ADD_OPTIONS_VERSION 1 92 #define GIT_WORKTREE_ADD_OPTIONS_INIT {GIT_WORKTREE_ADD_OPTIONS_VERSION,0,NULL} 93 94 /** 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`. 99 * 100 * @param opts The `git_worktree_add_options` struct to initialize. 101 * @param version The struct version; pass `GIT_WORKTREE_ADD_OPTIONS_VERSION`. 102 * @return Zero on success; -1 on failure. 103 */ 104 GIT_EXTERN(int) git_worktree_add_options_init(git_worktree_add_options *opts, 105 unsigned int version); 106 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 118 * @param opts Options to modify default behavior. May be NULL 119 * @return 0 or an error code 120 */ 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); 124 125 /** 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 */ 135 GIT_EXTERN(int) git_worktree_lock(git_worktree *wt, const char *reason); 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 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); 177 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 191 /** 192 * Worktree prune options structure 193 * 194 * Initialize with `GIT_WORKTREE_PRUNE_OPTIONS_INIT`. Alternatively, you can 195 * use `git_worktree_prune_options_init`. 196 * 197 */ 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 /** 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`. 212 * 213 * @param opts The `git_worktree_prune_options` struct to initialize. 214 * @param version The struct version; pass `GIT_WORKTREE_PRUNE_OPTIONS_VERSION`. 215 * @return Zero on success; -1 on failure. 216 */ 217 GIT_EXTERN(int) git_worktree_prune_options_init( 218 git_worktree_prune_options *opts, 219 unsigned int version); 220 221 /** 222 * Is the worktree prunable with the given options? 223 * 224 * A worktree is not prunable in the following scenarios: 225 * 226 * - the worktree is linking to a valid on-disk worktree. The 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. 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 */ 235 GIT_EXTERN(int) git_worktree_is_prunable(git_worktree *wt, 236 git_worktree_prune_options *opts); 237 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 246 * @param opts Specifies which checks to override. See 247 * `git_worktree_is_prunable`. May be NULL 248 * @return 0 or an error code 249 */ 250 GIT_EXTERN(int) git_worktree_prune(git_worktree *wt, 251 git_worktree_prune_options *opts); 252 253 /** @} */ 254 GIT_END_DECL 255 #endif 256