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