include/git2/worktree.h

   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  * @return 0 or an error code
  56  */
  57 GIT_EXTERN(int) git_worktree_open_from_repository(git_worktree **out, git_repository *repo);
  58
  59 /**
  60  * Free a previously allocated worktree
  61  *
  62  * @param wt worktree handle to close. If NULL nothing occurs.
  63  */
  64 GIT_EXTERN(void) git_worktree_free(git_worktree *wt);
  65
  66 /**
  67  * Check if worktree is valid
  68  *
  69  * A valid worktree requires both the git data structures inside
  70  * the linked parent repository and the linked working copy to be
  71  * present.
  72  *
  73  * @param wt Worktree to check
  74  * @return 0 when worktree is valid, error-code otherwise
  75  */
  76 GIT_EXTERN(int) git_worktree_validate(const git_worktree *wt);
  77
  78 /**
  79  * Worktree add options structure
  80  *
  81  * Initialize with `GIT_WORKTREE_ADD_OPTIONS_INIT`. Alternatively, you can
  82  * use `git_worktree_add_options_init`.
  83  *
  84  */
  85 typedef struct git_worktree_add_options {
  86         unsigned int version;
  87
  88         int lock; /**< lock newly created worktree */
  89         git_reference *ref; /**< reference to use for the new worktree HEAD */
  90
  91         /**
  92          * Options for the checkout.
  93          */
  94         git_checkout_options checkout_options;
  95 } git_worktree_add_options;
  96
  97 #define GIT_WORKTREE_ADD_OPTIONS_VERSION 1
  98 #define GIT_WORKTREE_ADD_OPTIONS_INIT {GIT_WORKTREE_ADD_OPTIONS_VERSION,0,NULL,GIT_CHECKOUT_OPTIONS_INIT}
  99
 100 /**
 101  * Initialize git_worktree_add_options structure
 102  *
 103  * Initializes a `git_worktree_add_options` with default values. Equivalent to
 104  * creating an instance with `GIT_WORKTREE_ADD_OPTIONS_INIT`.
 105  *
 106  * @param opts The `git_worktree_add_options` struct to initialize.
 107  * @param version The struct version; pass `GIT_WORKTREE_ADD_OPTIONS_VERSION`.
 108  * @return Zero on success; -1 on failure.
 109  */
 110 GIT_EXTERN(int) git_worktree_add_options_init(git_worktree_add_options *opts,
 111         unsigned int version);
 112
 113 /**
 114  * Add a new working tree
 115  *
 116  * Add a new working tree for the repository, that is create the
 117  * required data structures inside the repository and check out
 118  * the current HEAD at `path`
 119  *
 120  * @param out Output pointer containing new working tree
 121  * @param repo Repository to create working tree for
 122  * @param name Name of the working tree
 123  * @param path Path to create working tree at
 124  * @param opts Options to modify default behavior. May be NULL
 125  * @return 0 or an error code
 126  */
 127 GIT_EXTERN(int) git_worktree_add(git_worktree **out, git_repository *repo,
 128         const char *name, const char *path,
 129         const git_worktree_add_options *opts);
 130
 131 /**
 132  * Lock worktree if not already locked
 133  *
 134  * Lock a worktree, optionally specifying a reason why the linked
 135  * working tree is being locked.
 136  *
 137  * @param wt Worktree to lock
 138  * @param reason Reason why the working tree is being locked
 139  * @return 0 on success, non-zero otherwise
 140  */
 141 GIT_EXTERN(int) git_worktree_lock(git_worktree *wt, const char *reason);
 142
 143 /**
 144  * Unlock a locked worktree
 145  *
 146  * @param wt Worktree to unlock
 147  * @return 0 on success, 1 if worktree was not locked, error-code
 148  *  otherwise
 149  */
 150 GIT_EXTERN(int) git_worktree_unlock(git_worktree *wt);
 151
 152 /**
 153  * Check if worktree is locked
 154  *
 155  * A worktree may be locked if the linked working tree is stored
 156  * on a portable device which is not available.
 157  *
 158  * @param reason Buffer to store reason in. If NULL no reason is stored.
 159  * @param wt Worktree to check
 160  * @return 0 when the working tree not locked, a value greater
 161  *  than zero if it is locked, less than zero if there was an
 162  *  error
 163  */
 164 GIT_EXTERN(int) git_worktree_is_locked(git_buf *reason, const git_worktree *wt);
 165
 166 /**
 167  * Retrieve the name of the worktree
 168  *
 169  * @param wt Worktree to get the name for
 170  * @return The worktree's name. The pointer returned is valid for the
 171  *  lifetime of the git_worktree
 172  */
 173 GIT_EXTERN(const char *) git_worktree_name(const git_worktree *wt);
 174
 175 /**
 176  * Retrieve the filesystem path for the worktree
 177  *
 178  * @param wt Worktree to get the path for
 179  * @return The worktree's filesystem path. The pointer returned
 180  *  is valid for the lifetime of the git_worktree.
 181  */
 182 GIT_EXTERN(const char *) git_worktree_path(const git_worktree *wt);
 183
 184 /**
 185  * Flags which can be passed to git_worktree_prune to alter its
 186  * behavior.
 187  */
 188 typedef enum {
 189         /* Prune working tree even if working tree is valid */
 190         GIT_WORKTREE_PRUNE_VALID = 1u << 0,
 191         /* Prune working tree even if it is locked */
 192         GIT_WORKTREE_PRUNE_LOCKED = 1u << 1,
 193         /* Prune checked out working tree */
 194         GIT_WORKTREE_PRUNE_WORKING_TREE = 1u << 2
 195 } git_worktree_prune_t;
 196
 197 /**
 198  * Worktree prune options structure
 199  *
 200  * Initialize with `GIT_WORKTREE_PRUNE_OPTIONS_INIT`. Alternatively, you can
 201  * use `git_worktree_prune_options_init`.
 202  *
 203  */
 204 typedef struct git_worktree_prune_options {
 205         unsigned int version;
 206
 207         /** A combination of `git_worktree_prune_t` */
 208         uint32_t flags;
 209 } git_worktree_prune_options;
 210
 211 #define GIT_WORKTREE_PRUNE_OPTIONS_VERSION 1
 212 #define GIT_WORKTREE_PRUNE_OPTIONS_INIT {GIT_WORKTREE_PRUNE_OPTIONS_VERSION,0}
 213
 214 /**
 215  * Initialize git_worktree_prune_options structure
 216  *
 217  * Initializes a `git_worktree_prune_options` with default values. Equivalent to
 218  * creating an instance with `GIT_WORKTREE_PRUNE_OPTIONS_INIT`.
 219  *
 220  * @param opts The `git_worktree_prune_options` struct to initialize.
 221  * @param version The struct version; pass `GIT_WORKTREE_PRUNE_OPTIONS_VERSION`.
 222  * @return Zero on success; -1 on failure.
 223  */
 224 GIT_EXTERN(int) git_worktree_prune_options_init(
 225         git_worktree_prune_options *opts,
 226         unsigned int version);
 227
 228 /**
 229  * Is the worktree prunable with the given options?
 230  *
 231  * A worktree is not prunable in the following scenarios:
 232  *
 233  * - the worktree is linking to a valid on-disk worktree. The
 234  *   `valid` member will cause this check to be ignored.
 235  * - the worktree is locked. The `locked` flag will cause this
 236  *   check to be ignored.
 237  *
 238  * If the worktree is not valid and not locked or if the above
 239  * flags have been passed in, this function will return a
 240  * positive value.
 241  *
 242  * @param wt Worktree to check.
 243  * @param opts The prunable options.
 244  * @return 1 if the worktree is prunable, 0 otherwise, or an error code.
 245  */
 246 GIT_EXTERN(int) git_worktree_is_prunable(git_worktree *wt,
 247         git_worktree_prune_options *opts);
 248
 249 /**
 250  * Prune working tree
 251  *
 252  * Prune the working tree, that is remove the git data
 253  * structures on disk. The repository will only be pruned of
 254  * `git_worktree_is_prunable` succeeds.
 255  *
 256  * @param wt Worktree to prune
 257  * @param opts Specifies which checks to override. See
 258  *        `git_worktree_is_prunable`. May be NULL
 259  * @return 0 or an error code
 260  */
 261 GIT_EXTERN(int) git_worktree_prune(git_worktree *wt,
 262         git_worktree_prune_options *opts);
 263
 264 /** @} */
 265 GIT_END_DECL
 266 #endif