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  */
  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  * Add a new working tree
  79  *
  80  * Add a new working tree for the repository, that is create the
  81  * required data structures inside the repository and check out
  82  * the current HEAD at `path`
  83  *
  84  * @param out Output pointer containing new working tree
  85  * @param repo Repository to create working tree for
  86  * @param name Name of the working tree
  87  * @param path Path to create working tree at
  88  * @return 0 or an error code
  89  */
  90 GIT_EXTERN(int) git_worktree_add(git_worktree **out, git_repository *repo, const char *name, const char *path);
  91
  92 /**
  93  * Lock worktree if not already locked
  94  *
  95  * Lock a worktree, optionally specifying a reason why the linked
  96  * working tree is being locked.
  97  *
  98  * @param wt Worktree to lock
  99  * @param reason Reason why the working tree is being locked
 100  * @return 0 on success, non-zero otherwise
 101  */
 102 GIT_EXTERN(int) git_worktree_lock(git_worktree *wt, char *reason);
 103
 104 /**
 105  * Unlock a locked worktree
 106  *
 107  * @param wt Worktree to unlock
 108  * @return 0 on success, 1 if worktree was not locked, error-code
 109  *  otherwise
 110  */
 111 GIT_EXTERN(int) git_worktree_unlock(git_worktree *wt);
 112
 113 /**
 114  * Check if worktree is locked
 115  *
 116  * A worktree may be locked if the linked working tree is stored
 117  * on a portable device which is not available.
 118  *
 119  * @param reason Buffer to store reason in. If NULL no reason is stored.
 120  * @param wt Worktree to check
 121  * @return 0 when the working tree not locked, a value greater
 122  *  than zero if it is locked, less than zero if there was an
 123  *  error
 124  */
 125 GIT_EXTERN(int) git_worktree_is_locked(git_buf *reason, const git_worktree *wt);
 126
 127 /**
 128  * Flags which can be passed to git_worktree_prune to alter its
 129  * behavior.
 130  */
 131 typedef enum {
 132         /* Prune working tree even if working tree is valid */
 133         GIT_WORKTREE_PRUNE_VALID = 1u << 0,
 134         /* Prune working tree even if it is locked */
 135         GIT_WORKTREE_PRUNE_LOCKED = 1u << 1,
 136         /* Prune checked out working tree */
 137         GIT_WORKTREE_PRUNE_WORKING_TREE = 1u << 2,
 138 } git_worktree_prune_t;
 139
 140 /**
 141  * Is the worktree prunable with the given set of flags?
 142  *
 143  * A worktree is not prunable in the following scenarios:
 144  *
 145  * - the worktree is linking to a valid on-disk worktree. The
 146  *   GIT_WORKTREE_PRUNE_VALID flag will cause this check to be
 147  *   ignored.
 148  * - the worktree is not valid but locked. The
 149  *   GIT_WORKRTEE_PRUNE_LOCKED flag will cause this check to be
 150  *   ignored.
 151  *
 152  * If the worktree is not valid and not locked or if the above
 153  * flags have been passed in, this function will return a
 154  * positive value.
 155  */
 156 GIT_EXTERN(int) git_worktree_is_prunable(git_worktree *wt, unsigned flags);
 157
 158 /**
 159  * Prune working tree
 160  *
 161  * Prune the working tree, that is remove the git data
 162  * structures on disk. The repository will only be pruned of
 163  * `git_worktree_is_prunable` succeeds.
 164  *
 165  * @param wt Worktree to prune
 166  * @param flags git_worktree_prune_t flags
 167  * @return 0 or an error code
 168  */
 169 GIT_EXTERN(int) git_worktree_prune(git_worktree *wt, unsigned flags);
 170
 171 /** @} */
 172 GIT_END_DECL
 173 #endif