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_CALLBACK(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_CALLBACK(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 * Initialize with `GIT_CLONE_OPTIONS_INIT`. Alternatively, you can 100 * use `git_clone_options_init`. 101 * 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`. 110 */ 111 git_checkout_options checkout_opts; 112 113 /** 114 * Options which control the fetch, including callbacks. 115 * 116 * The callbacks are used for reporting fetch progress, and for acquiring 117 * credentials in the event they are needed. 118 */ 119 git_fetch_options fetch_opts; 120 121 /** 122 * Set to zero (false) to create a standard repo, or non-zero 123 * for a bare repo 124 */ 125 int bare; 126 127 /** 128 * Whether to use a fetch or copy the object database. 129 */ 130 git_clone_local_t local; 131 132 /** 133 * The name of the branch to checkout. NULL means use the 134 * remote's default branch. 135 */ 136 const char* checkout_branch; 137 138 /** 139 * A callback used to create the new repository into which to 140 * clone. If NULL, the 'bare' field will be used to determine 141 * whether to create a bare repository. 142 */ 143 git_repository_create_cb repository_cb; 144 145 /** 146 * An opaque payload to pass to the git_repository creation callback. 147 * This parameter is ignored unless repository_cb is non-NULL. 148 */ 149 void *repository_cb_payload; 150 151 /** 152 * A callback used to create the git_remote, prior to its being 153 * used to perform the clone operation. See the documentation for 154 * git_remote_create_cb for details. This parameter may be NULL, 155 * indicating that git_clone should provide default behavior. 156 */ 157 git_remote_create_cb remote_cb; 158 159 /** 160 * An opaque payload to pass to the git_remote creation callback. 161 * This parameter is ignored unless remote_cb is non-NULL. 162 */ 163 void *remote_cb_payload; 164 } git_clone_options; 165 166 #define GIT_CLONE_OPTIONS_VERSION 1 167 #define GIT_CLONE_OPTIONS_INIT { GIT_CLONE_OPTIONS_VERSION, \ 168 { GIT_CHECKOUT_OPTIONS_VERSION, GIT_CHECKOUT_SAFE }, \ 169 GIT_FETCH_OPTIONS_INIT } 170 171 /** 172 * Initialize git_clone_options structure 173 * 174 * Initializes a `git_clone_options` with default values. Equivalent to creating 175 * an instance with GIT_CLONE_OPTIONS_INIT. 176 * 177 * @param opts The `git_clone_options` struct to initialize. 178 * @param version The struct version; pass `GIT_CLONE_OPTIONS_VERSION`. 179 * @return Zero on success; -1 on failure. 180 */ 181 GIT_EXTERN(int) git_clone_options_init( 182 git_clone_options *opts, 183 unsigned int version); 184 185 /** 186 * Clone a remote repository. 187 * 188 * By default this creates its repository and initial remote to match 189 * git's defaults. You can use the options in the callback to 190 * customize how these are created. 191 * 192 * @param out pointer that will receive the resulting repository object 193 * @param url the remote repository to clone 194 * @param local_path local directory to clone to 195 * @param options configuration options for the clone. If NULL, the 196 * function works as though GIT_OPTIONS_INIT were passed. 197 * @return 0 on success, any non-zero return value from a callback 198 * function, or a negative value to indicate an error (use 199 * `git_error_last` for a detailed error message) 200 */ 201 GIT_EXTERN(int) git_clone( 202 git_repository **out, 203 const char *url, 204 const char *local_path, 205 const git_clone_options *options); 206 207 /** @} */ 208 GIT_END_DECL 209 #endif 210