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 typedef enum {
  27         GIT_CLONE_LOCAL_AUTO,
  28         GIT_CLONE_LOCAL,
  29         GIT_CLONE_NO_LOCAL,
  30         GIT_CLONE_LOCAL_NO_LINKS,
  31 } git_clone_local_t;
  32
  33 /**
  34  * Clone options structure
  35  *
  36  * Use the GIT_CLONE_OPTIONS_INIT to get the default settings, like this:
  37  *
  38  *              git_clone_options opts = GIT_CLONE_OPTIONS_INIT;
  39  *
  40  * - `checkout_opts` are option passed to the checkout step.  To disable
  41  *   checkout, set the `checkout_strategy` to GIT_CHECKOUT_NONE.
  42  *   Generally you will want the use GIT_CHECKOUT_SAFE_CREATE to create
  43  *   all files in the working directory for the newly cloned repository.
  44  * - `bare` should be set to zero (false) to create a standard repo,
  45  *   or non-zero for a bare repo
  46  * - `ignore_cert_errors` should be set to 1 if errors validating the
  47  *   remote host's certificate should be ignored.
  48  *
  49  *   ** "origin" remote options: **
  50  *
  51  * - `remote_name` is the name to be given to the "origin" remote.  The
  52  *   default is "origin".
  53  * - `checkout_branch` gives the name of the branch to checkout.  NULL
  54  *   means use the remote's HEAD.
  55  * - `signature` is the identity used when updating the reflog. NULL means to
  56  *   use the default signature using the config.
  57  */
  58
  59 typedef struct git_clone_options {
  60         unsigned int version;
  61
  62         git_checkout_options checkout_opts;
  63         git_remote_callbacks remote_callbacks;
  64
  65         int bare;
  66         int ignore_cert_errors;
  67         git_clone_local_t local;
  68         const char *remote_name;
  69         const char* checkout_branch;
  70         git_signature *signature;
  71 } git_clone_options;
  72
  73 #define GIT_CLONE_OPTIONS_VERSION 1
  74 #define GIT_CLONE_OPTIONS_INIT {GIT_CLONE_OPTIONS_VERSION, {GIT_CHECKOUT_OPTIONS_VERSION, GIT_CHECKOUT_SAFE_CREATE}, GIT_REMOTE_CALLBACKS_INIT}
  75
  76 /**
  77  * Initializes a `git_clone_options` with default values. Equivalent to
  78  * creating an instance with GIT_CLONE_OPTIONS_INIT.
  79  *
  80  * @param opts The `git_clone_options` struct to initialize
  81  * @param version Version of struct; pass `GIT_CLONE_OPTIONS_VERSION`
  82  * @return Zero on success; -1 on failure.
  83  */
  84 GIT_EXTERN(int) git_clone_init_options(
  85         git_clone_options *opts,
  86         unsigned int version);
  87
  88 /**
  89  * Clone a remote repository.
  90  *
  91  * This version handles the simple case. If you'd like to create the
  92  * repository or remote with non-default settings, you can create and
  93  * configure them and then use `git_clone_into()`.
  94  *
  95  * @param out pointer that will receive the resulting repository object
  96  * @param url the remote repository to clone
  97  * @param local_path local directory to clone to
  98  * @param options configuration options for the clone.  If NULL, the
  99  *        function works as though GIT_OPTIONS_INIT were passed.
 100  * @return 0 on success, any non-zero return value from a callback
 101  *         function, or a negative value to indicate an error (use
 102  *         `giterr_last` for a detailed error message)
 103  */
 104 GIT_EXTERN(int) git_clone(
 105         git_repository **out,
 106         const char *url,
 107         const char *local_path,
 108         const git_clone_options *options);
 109
 110 /**
 111  * Clone into a repository
 112  *
 113  * After creating the repository and remote and configuring them for
 114  * paths and callbacks respectively, you can call this function to
 115  * perform the clone operation and optionally checkout files.
 116  *
 117  * @param repo the repository to use
 118  * @param remote the remote repository to clone from
 119  * @param co_opts options to use during checkout
 120  * @param branch the branch to checkout after the clone, pass NULL for the
 121  *        remote's default branch
 122  * @param signature The identity used when updating the reflog.
 123  * @return 0 on success, any non-zero return value from a callback
 124  *         function, or a negative value to indicate an error (use
 125  *         `giterr_last` for a detailed error message)
 126  */
 127 GIT_EXTERN(int) git_clone_into(
 128         git_repository *repo,
 129         git_remote *remote,
 130         const git_checkout_options *co_opts,
 131         const char *branch,
 132         const git_signature *signature);
 133
 134 /**
 135  * Perform a local clone into a repository
 136  *
 137  * A "local clone" bypasses any git-aware protocols and simply copies
 138  * over the object database from the source repository. It is often
 139  * faster than a git-aware clone, but no verification of the data is
 140  * performed, and can copy over too much data.
 141  *
 142  * @param repo the repository to use
 143  * @param remote the remote repository to clone from
 144  * @param co_opts options to use during checkout
 145  * @param branch the branch to checkout after the clone, pass NULL for the
 146  *        remote's default branch
 147  * @param link wether to use hardlinks instead of copying
 148  * objects. This is only possible if both repositories are on the same
 149  * filesystem.
 150  * @param signature the identity used when updating the reflog
 151  * @return 0 on success, any non-zero return value from a callback
 152  *         function, or a negative value to indicate an error (use
 153  *         `giterr_last` for a detailed error message)
 154  */
 155 GIT_EXTERN(int) git_clone_local_into(
 156         git_repository *repo,
 157         git_remote *remote,
 158         const git_checkout_options *co_opts,
 159         const char *branch,
 160         int link,
 161         const git_signature *signature);
 162
 163 /** @} */
 164 GIT_END_DECL
 165 #endif