include/git2/clone.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_clone_h__
   8 #define INCLUDE_git_clone_h__
   9
  10 #include "common.h"
  11 #include "types.h"
  12 #include "indexer.h"
  13 #include "checkout.h"
  14 #include "remote.h"
  15 #include "transport.h"
  16
  17
  18 /**
  19  * @file git2/clone.h
  20  * @brief Git cloning routines
  21  * @defgroup git_clone Git cloning routines
  22  * @ingroup Git
  23  * @{
  24  */
  25 GIT_BEGIN_DECL
  26
  27 /**
  28  * Options for bypassing the git-aware transport on clone. Bypassing
  29  * it means that instead of a fetch, libgit2 will copy the object
  30  * database directory instead of figuring out what it needs, which is
  31  * faster. If possible, it will hardlink the files to save space.
  32  */
  33 typedef enum {
  34         /**
  35          * Auto-detect (default), libgit2 will bypass the git-aware
  36          * transport for local paths, but use a normal fetch for
  37          * `file://` urls.
  38          */
  39         GIT_CLONE_LOCAL_AUTO,
  40         /**
  41          * Bypass the git-aware transport even for a `file://` url.
  42          */
  43         GIT_CLONE_LOCAL,
  44         /**
  45          * Do no bypass the git-aware transport
  46          */
  47         GIT_CLONE_NO_LOCAL,
  48         /**
  49          * Bypass the git-aware transport, but do not try to use
  50          * hardlinks.
  51          */
  52         GIT_CLONE_LOCAL_NO_LINKS,
  53 } git_clone_local_t;
  54
  55 /**
  56  * The signature of a function matching git_remote_create, with an additional
  57  * void* as a callback payload.
  58  *
  59  * Callers of git_clone may provide a function matching this signature to override
  60  * the remote creation and customization process during a clone operation.
  61  *
  62  * @param out the resulting remote
  63  * @param repo the repository in which to create the remote
  64  * @param name the remote's name
  65  * @param url the remote's url
  66  * @param payload an opaque payload
  67  * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code
  68  */
  69 typedef int (*git_remote_create_cb)(
  70         git_remote **out,
  71         git_repository *repo,
  72         const char *name,
  73         const char *url,
  74         void *payload);
  75
  76 /**
  77  * Clone options structure
  78  *
  79  * Use the GIT_CLONE_OPTIONS_INIT to get the default settings, like this:
  80  *
  81  *              git_clone_options opts = GIT_CLONE_OPTIONS_INIT;
  82  */
  83
  84 typedef struct git_clone_options {
  85         unsigned int version;
  86
  87         /**
  88          * These options are passed to the checkout step. To disable
  89          * checkout, set the `checkout_strategy` to
  90          * `GIT_CHECKOUT_NONE`. Generally you will want the use
  91          * GIT_CHECKOUT_SAFE_CREATE to create all files in the working
  92          * directory for the newly cloned repository.
  93          */
  94         git_checkout_options checkout_opts;
  95
  96         /**
  97          * Callbacks to use for reporting fetch progress, and for acquiring
  98          * credentials in the event they are needed. This parameter is ignored if
  99          * the remote_cb parameter is set; if you provide a remote creation
 100          * callback, then you have the opportunity to configure remote callbacks in
 101          * provided function.
 102          */
 103         git_remote_callbacks remote_callbacks;
 104
 105         /**
 106          * Set to zero (false) to create a standard repo, or non-zero
 107          * for a bare repo
 108          */
 109         int bare;
 110
 111         /**
 112          * Whether to use a fetch or copy the object database.
 113          */
 114         git_clone_local_t local;
 115
 116         /**
 117          * The name of the branch to checkout. NULL means use the
 118          * remote's default branch.
 119          */
 120         const char* checkout_branch;
 121
 122         /**
 123          * The identity used when updating the reflog. NULL means to
 124          * use the default signature using the config.
 125          */
 126         git_signature *signature;
 127
 128         /**
 129          * A callback used to create the git_remote, prior to its being
 130          * used to perform the clone operation. See the documentation for
 131          * git_remote_create_cb for details. This parameter may be NULL,
 132          * indicating that git_clone should provide default behavior.
 133          */
 134         git_remote_create_cb remote_cb;
 135
 136         /**
 137          * An opaque payload to pass to the git_remote creation callback.
 138          * This parameter is ignored unless remote_cb is non-NULL.
 139          */
 140         void *remote_cb_payload;
 141 } git_clone_options;
 142
 143 #define GIT_CLONE_OPTIONS_VERSION 1
 144 #define GIT_CLONE_OPTIONS_INIT {GIT_CLONE_OPTIONS_VERSION, {GIT_CHECKOUT_OPTIONS_VERSION, GIT_CHECKOUT_SAFE_CREATE}, GIT_REMOTE_CALLBACKS_INIT}
 145
 146 /**
 147  * Initializes a `git_clone_options` with default values. Equivalent to
 148  * creating an instance with GIT_CLONE_OPTIONS_INIT.
 149  *
 150  * @param opts The `git_clone_options` struct to initialize
 151  * @param version Version of struct; pass `GIT_CLONE_OPTIONS_VERSION`
 152  * @return Zero on success; -1 on failure.
 153  */
 154 GIT_EXTERN(int) git_clone_init_options(
 155         git_clone_options *opts,
 156         unsigned int version);
 157
 158 /**
 159  * Clone a remote repository.
 160  *
 161  * This version handles the simple case. If you'd like to create the
 162  * repository or remote with non-default settings, you can create and
 163  * configure them and then use `git_clone_into()`.
 164  *
 165  * @param out pointer that will receive the resulting repository object
 166  * @param url the remote repository to clone
 167  * @param local_path local directory to clone to
 168  * @param options configuration options for the clone.  If NULL, the
 169  *        function works as though GIT_OPTIONS_INIT were passed.
 170  * @return 0 on success, any non-zero return value from a callback
 171  *         function, or a negative value to indicate an error (use
 172  *         `giterr_last` for a detailed error message)
 173  */
 174 GIT_EXTERN(int) git_clone(
 175         git_repository **out,
 176         const char *url,
 177         const char *local_path,
 178         const git_clone_options *options);
 179
 180 /**
 181  * Clone into a repository
 182  *
 183  * After creating the repository and remote and configuring them for
 184  * paths and callbacks respectively, you can call this function to
 185  * perform the clone operation and optionally checkout files.
 186  *
 187  * @param repo the repository to use
 188  * @param remote the remote repository to clone from
 189  * @param co_opts options to use during checkout
 190  * @param branch the branch to checkout after the clone, pass NULL for the
 191  *        remote's default branch
 192  * @param signature The identity used when updating the reflog.
 193  * @return 0 on success, any non-zero return value from a callback
 194  *         function, or a negative value to indicate an error (use
 195  *         `giterr_last` for a detailed error message)
 196  */
 197 GIT_EXTERN(int) git_clone_into(
 198         git_repository *repo,
 199         git_remote *remote,
 200         const git_checkout_options *co_opts,
 201         const char *branch,
 202         const git_signature *signature);
 203
 204 /**
 205  * Perform a local clone into a repository
 206  *
 207  * A "local clone" bypasses any git-aware protocols and simply copies
 208  * over the object database from the source repository. It is often
 209  * faster than a git-aware clone, but no verification of the data is
 210  * performed, and can copy over too much data.
 211  *
 212  * @param repo the repository to use
 213  * @param remote the remote repository to clone from
 214  * @param co_opts options to use during checkout
 215  * @param branch the branch to checkout after the clone, pass NULL for the
 216  *        remote's default branch
 217  * @param link wether to use hardlinks instead of copying
 218  * objects. This is only possible if both repositories are on the same
 219  * filesystem.
 220  * @param signature the identity used when updating the reflog
 221  * @return 0 on success, any non-zero return value from a callback
 222  *         function, or a negative value to indicate an error (use
 223  *         `giterr_last` for a detailed error message)
 224  */
 225 GIT_EXTERN(int) git_clone_local_into(
 226         git_repository *repo,
 227         git_remote *remote,
 228         const git_checkout_options *co_opts,
 229         const char *branch,
 230         int link,
 231         const git_signature *signature);
 232
 233 /** @} */
 234 GIT_END_DECL
 235 #endif