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  * The signature of a function matchin git_repository_init, with an
  78  * aditional void * as callback payload.
  79  *
  80  * Callers of git_clone my provide a function matching this signature
  81  * to override the repository creation and customization process
  82  * during a clone operation.
  83  *
  84  * @param out the resulting repository
  85  * @param path path in which to create the repository
  86  * @param bare whether the repository is bare. This is the value from the clone options
  87  * @param payload payload specified by the options
  88  * @return 0, or a negative value to indicate error
  89  */
  90 typedef int (*git_repository_create_cb)(
  91         git_repository **out,
  92         const char *path,
  93         int bare,
  94         void *payload);
  95
  96 /**
  97  * Clone options structure
  98  *
  99  * Use the GIT_CLONE_OPTIONS_INIT to get the default settings, like this:
 100  *
 101  *              git_clone_options opts = GIT_CLONE_OPTIONS_INIT;
 102  */
 103 typedef struct git_clone_options {
 104         unsigned int version;
 105
 106         /**
 107          * These options are passed to the checkout step. To disable
 108          * checkout, set the `checkout_strategy` to
 109          * `GIT_CHECKOUT_NONE`. Generally you will want the use
 110          * GIT_CHECKOUT_SAFE_CREATE to create all files in the working
 111          * directory for the newly cloned repository.
 112          */
 113         git_checkout_options checkout_opts;
 114
 115         /**
 116          * Callbacks to use for reporting fetch progress, and for acquiring
 117          * credentials in the event they are needed. This parameter is ignored if
 118          * the remote_cb parameter is set; if you provide a remote creation
 119          * callback, then you have the opportunity to configure remote callbacks in
 120          * provided function.
 121          */
 122         git_remote_callbacks remote_callbacks;
 123
 124         /**
 125          * Set to zero (false) to create a standard repo, or non-zero
 126          * for a bare repo
 127          */
 128         int bare;
 129
 130         /**
 131          * Whether to use a fetch or copy the object database.
 132          */
 133         git_clone_local_t local;
 134
 135         /**
 136          * The name of the branch to checkout. NULL means use the
 137          * remote's default branch.
 138          */
 139         const char* checkout_branch;
 140
 141         /**
 142          * The identity used when updating the reflog. NULL means to
 143          * use the default signature using the config.
 144          */
 145         git_signature *signature;
 146
 147         /**
 148          * A callback used to create the new repository into which to
 149          * clone. If NULL, the 'bare' field will be used to determine
 150          * whether to create a bare repository.
 151          */
 152         git_repository_create_cb repository_cb;
 153
 154         /**
 155          * An opaque payload to pass to the git_repository creation callback.
 156          * This parameter is ignored unless repository_cb is non-NULL.
 157          */
 158         void *repository_cb_payload;
 159
 160         /**
 161          * A callback used to create the git_remote, prior to its being
 162          * used to perform the clone operation. See the documentation for
 163          * git_remote_create_cb for details. This parameter may be NULL,
 164          * indicating that git_clone should provide default behavior.
 165          */
 166         git_remote_create_cb remote_cb;
 167
 168         /**
 169          * An opaque payload to pass to the git_remote creation callback.
 170          * This parameter is ignored unless remote_cb is non-NULL.
 171          */
 172         void *remote_cb_payload;
 173 } git_clone_options;
 174
 175 #define GIT_CLONE_OPTIONS_VERSION 1
 176 #define GIT_CLONE_OPTIONS_INIT {GIT_CLONE_OPTIONS_VERSION, {GIT_CHECKOUT_OPTIONS_VERSION, GIT_CHECKOUT_SAFE_CREATE}, GIT_REMOTE_CALLBACKS_INIT}
 177
 178 /**
 179  * Initializes a `git_clone_options` with default values. Equivalent to
 180  * creating an instance with GIT_CLONE_OPTIONS_INIT.
 181  *
 182  * @param opts The `git_clone_options` struct to initialize
 183  * @param version Version of struct; pass `GIT_CLONE_OPTIONS_VERSION`
 184  * @return Zero on success; -1 on failure.
 185  */
 186 GIT_EXTERN(int) git_clone_init_options(
 187         git_clone_options *opts,
 188         unsigned int version);
 189
 190 /**
 191  * Clone a remote repository.
 192  *
 193  * By default this creates its repository and initial remote to match
 194  * git's defaults. You can use the options in the callback to
 195  * customize how these are created.
 196  *
 197  * @param out pointer that will receive the resulting repository object
 198  * @param url the remote repository to clone
 199  * @param local_path local directory to clone to
 200  * @param options configuration options for the clone.  If NULL, the
 201  *        function works as though GIT_OPTIONS_INIT were passed.
 202  * @return 0 on success, any non-zero return value from a callback
 203  *         function, or a negative value to indicate an error (use
 204  *         `giterr_last` for a detailed error message)
 205  */
 206 GIT_EXTERN(int) git_clone(
 207         git_repository **out,
 208         const char *url,
 209         const char *local_path,
 210         const git_clone_options *options);
 211
 212 /** @} */
 213 GIT_END_DECL
 214 #endif