include/git2/worktree.h

0001 /*
0002  * Copyright (C) the libgit2 contributors. All rights reserved.
0003  *
0004  * This file is part of libgit2, distributed under the GNU GPL v2 with
0005  * a Linking Exception. For full terms see the included COPYING file.
0006  */
0007 #ifndef INCLUDE_git_worktree_h__
0008 #define INCLUDE_git_worktree_h__
0009
0010 #include "common.h"
0011 #include "buffer.h"
0012 #include "types.h"
0013 #include "strarray.h"
0014
0015 /**
0016  * @file git2/worktrees.h
0017  * @brief Git worktree related functions
0018  * @defgroup git_commit Git worktree related functions
0019  * @ingroup Git
0020  * @{
0021  */
0022 GIT_BEGIN_DECL
0023
0024 /**
0025  * List names of linked working trees
0026  *
0027  * The returned list should be released with `git_strarray_free`
0028  * when no longer needed.
0029  *
0030  * @param out pointer to the array of working tree names
0031  * @param repo the repo to use when listing working trees
0032  * @return 0 or an error code
0033  */
0034 GIT_EXTERN(int) git_worktree_list(git_strarray *out, git_repository *repo);
0035
0036 /**
0037  * Lookup a working tree by its name for a given repository
0038  *
0039  * @param out Output pointer to looked up worktree or `NULL`
0040  * @param repo The repository containing worktrees
0041  * @param name Name of the working tree to look up
0042  * @return 0 or an error code
0043  */
0044 GIT_EXTERN(int) git_worktree_lookup(git_worktree **out, git_repository *repo, const char *name);
0045
0046 /**
0047  * Open a worktree of a given repository
0048  *
0049  * If a repository is not the main tree but a worktree, this
0050  * function will look up the worktree inside the parent
0051  * repository and create a new `git_worktree` structure.
0052  *
0053  * @param out Out-pointer for the newly allocated worktree
0054  * @param repo Repository to look up worktree for
0055  * @return 0 or an error code
0056  */
0057 GIT_EXTERN(int) git_worktree_open_from_repository(git_worktree **out, git_repository *repo);
0058
0059 /**
0060  * Free a previously allocated worktree
0061  *
0062  * @param wt worktree handle to close. If NULL nothing occurs.
0063  */
0064 GIT_EXTERN(void) git_worktree_free(git_worktree *wt);
0065
0066 /**
0067  * Check if worktree is valid
0068  *
0069  * A valid worktree requires both the git data structures inside
0070  * the linked parent repository and the linked working copy to be
0071  * present.
0072  *
0073  * @param wt Worktree to check
0074  * @return 0 when worktree is valid, error-code otherwise
0075  */
0076 GIT_EXTERN(int) git_worktree_validate(const git_worktree *wt);
0077
0078 /**
0079  * Worktree add options structure
0080  *
0081  * Initialize with `GIT_WORKTREE_ADD_OPTIONS_INIT`. Alternatively, you can
0082  * use `git_worktree_add_options_init`.
0083  *
0084  */
0085 typedef struct git_worktree_add_options {
0086     unsigned int version;
0087
0088     int lock;       /**< lock newly created worktree */
0089     int checkout_existing;  /**< allow checkout of existing branch matching worktree name */
0090     git_reference *ref; /**< reference to use for the new worktree HEAD */
0091
0092     /**
0093      * Options for the checkout.
0094      */
0095     git_checkout_options checkout_options;
0096 } git_worktree_add_options;
0097
0098 #define GIT_WORKTREE_ADD_OPTIONS_VERSION 1
0099 #define GIT_WORKTREE_ADD_OPTIONS_INIT { GIT_WORKTREE_ADD_OPTIONS_VERSION, \
0100     0, 0, NULL, GIT_CHECKOUT_OPTIONS_INIT }
0101
0102 /**
0103  * Initialize git_worktree_add_options structure
0104  *
0105  * Initializes a `git_worktree_add_options` with default values. Equivalent to
0106  * creating an instance with `GIT_WORKTREE_ADD_OPTIONS_INIT`.
0107  *
0108  * @param opts The `git_worktree_add_options` struct to initialize.
0109  * @param version The struct version; pass `GIT_WORKTREE_ADD_OPTIONS_VERSION`.
0110  * @return Zero on success; -1 on failure.
0111  */
0112 GIT_EXTERN(int) git_worktree_add_options_init(git_worktree_add_options *opts,
0113     unsigned int version);
0114
0115 /**
0116  * Add a new working tree
0117  *
0118  * Add a new working tree for the repository, that is create the
0119  * required data structures inside the repository and check out
0120  * the current HEAD at `path`
0121  *
0122  * @param out Output pointer containing new working tree
0123  * @param repo Repository to create working tree for
0124  * @param name Name of the working tree
0125  * @param path Path to create working tree at
0126  * @param opts Options to modify default behavior. May be NULL
0127  * @return 0 or an error code
0128  */
0129 GIT_EXTERN(int) git_worktree_add(git_worktree **out, git_repository *repo,
0130     const char *name, const char *path,
0131     const git_worktree_add_options *opts);
0132
0133 /**
0134  * Lock worktree if not already locked
0135  *
0136  * Lock a worktree, optionally specifying a reason why the linked
0137  * working tree is being locked.
0138  *
0139  * @param wt Worktree to lock
0140  * @param reason Reason why the working tree is being locked
0141  * @return 0 on success, non-zero otherwise
0142  */
0143 GIT_EXTERN(int) git_worktree_lock(git_worktree *wt, const char *reason);
0144
0145 /**
0146  * Unlock a locked worktree
0147  *
0148  * @param wt Worktree to unlock
0149  * @return 0 on success, 1 if worktree was not locked, error-code
0150  *  otherwise
0151  */
0152 GIT_EXTERN(int) git_worktree_unlock(git_worktree *wt);
0153
0154 /**
0155  * Check if worktree is locked
0156  *
0157  * A worktree may be locked if the linked working tree is stored
0158  * on a portable device which is not available.
0159  *
0160  * @param reason Buffer to store reason in. If NULL no reason is stored.
0161  * @param wt Worktree to check
0162  * @return 0 when the working tree not locked, a value greater
0163  *  than zero if it is locked, less than zero if there was an
0164  *  error
0165  */
0166 GIT_EXTERN(int) git_worktree_is_locked(git_buf *reason, const git_worktree *wt);
0167
0168 /**
0169  * Retrieve the name of the worktree
0170  *
0171  * @param wt Worktree to get the name for
0172  * @return The worktree's name. The pointer returned is valid for the
0173  *  lifetime of the git_worktree
0174  */
0175 GIT_EXTERN(const char *) git_worktree_name(const git_worktree *wt);
0176
0177 /**
0178  * Retrieve the filesystem path for the worktree
0179  *
0180  * @param wt Worktree to get the path for
0181  * @return The worktree's filesystem path. The pointer returned
0182  *  is valid for the lifetime of the git_worktree.
0183  */
0184 GIT_EXTERN(const char *) git_worktree_path(const git_worktree *wt);
0185
0186 /**
0187  * Flags which can be passed to git_worktree_prune to alter its
0188  * behavior.
0189  */
0190 typedef enum {
0191     /* Prune working tree even if working tree is valid */
0192     GIT_WORKTREE_PRUNE_VALID = 1u << 0,
0193     /* Prune working tree even if it is locked */
0194     GIT_WORKTREE_PRUNE_LOCKED = 1u << 1,
0195     /* Prune checked out working tree */
0196     GIT_WORKTREE_PRUNE_WORKING_TREE = 1u << 2
0197 } git_worktree_prune_t;
0198
0199 /**
0200  * Worktree prune options structure
0201  *
0202  * Initialize with `GIT_WORKTREE_PRUNE_OPTIONS_INIT`. Alternatively, you can
0203  * use `git_worktree_prune_options_init`.
0204  *
0205  */
0206 typedef struct git_worktree_prune_options {
0207     unsigned int version;
0208
0209     /** A combination of `git_worktree_prune_t` */
0210     uint32_t flags;
0211 } git_worktree_prune_options;
0212
0213 #define GIT_WORKTREE_PRUNE_OPTIONS_VERSION 1
0214 #define GIT_WORKTREE_PRUNE_OPTIONS_INIT {GIT_WORKTREE_PRUNE_OPTIONS_VERSION,0}
0215
0216 /**
0217  * Initialize git_worktree_prune_options structure
0218  *
0219  * Initializes a `git_worktree_prune_options` with default values. Equivalent to
0220  * creating an instance with `GIT_WORKTREE_PRUNE_OPTIONS_INIT`.
0221  *
0222  * @param opts The `git_worktree_prune_options` struct to initialize.
0223  * @param version The struct version; pass `GIT_WORKTREE_PRUNE_OPTIONS_VERSION`.
0224  * @return Zero on success; -1 on failure.
0225  */
0226 GIT_EXTERN(int) git_worktree_prune_options_init(
0227     git_worktree_prune_options *opts,
0228     unsigned int version);
0229
0230 /**
0231  * Is the worktree prunable with the given options?
0232  *
0233  * A worktree is not prunable in the following scenarios:
0234  *
0235  * - the worktree is linking to a valid on-disk worktree. The
0236  *   `valid` member will cause this check to be ignored.
0237  * - the worktree is locked. The `locked` flag will cause this
0238  *   check to be ignored.
0239  *
0240  * If the worktree is not valid and not locked or if the above
0241  * flags have been passed in, this function will return a
0242  * positive value. If the worktree is not prunable, an error
0243  * message will be set (visible in `giterr_last`) with details about
0244  * why.
0245  *
0246  * @param wt Worktree to check.
0247  * @param opts The prunable options.
0248  * @return 1 if the worktree is prunable, 0 otherwise, or an error code.
0249  */
0250 GIT_EXTERN(int) git_worktree_is_prunable(git_worktree *wt,
0251     git_worktree_prune_options *opts);
0252
0253 /**
0254  * Prune working tree
0255  *
0256  * Prune the working tree, that is remove the git data
0257  * structures on disk. The repository will only be pruned of
0258  * `git_worktree_is_prunable` succeeds.
0259  *
0260  * @param wt Worktree to prune
0261  * @param opts Specifies which checks to override. See
0262  *        `git_worktree_is_prunable`. May be NULL
0263  * @return 0 or an error code
0264  */
0265 GIT_EXTERN(int) git_worktree_prune(git_worktree *wt,
0266     git_worktree_prune_options *opts);
0267
0268 /** @} */
0269 GIT_END_DECL
0270 #endif