2 * Copyright (C) the libgit2 contributors. All rights reserved.
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.
7 #ifndef INCLUDE_git_clone_h__
8 #define INCLUDE_git_clone_h__
19 * @brief Git cloning routines
20 * @defgroup git_clone Git cloning routines
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.
34 * Auto-detect (default), libgit2 will bypass the git-aware
35 * transport for local paths, but use a normal fetch for
40 * Bypass the git-aware transport even for a `file://` url.
44 * Do no bypass the git-aware transport
48 * Bypass the git-aware transport, but do not try to use
51 GIT_CLONE_LOCAL_NO_LINKS
,
55 * Clone options structure
57 * Use the GIT_CLONE_OPTIONS_INIT to get the default settings, like this:
59 * git_clone_options opts = GIT_CLONE_OPTIONS_INIT;
62 typedef struct git_clone_options
{
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.
72 git_checkout_options checkout_opts
;
75 * Callbacks to use for reporting fetch progress.
77 git_remote_callbacks remote_callbacks
;
80 * Set to zero (false) to create a standard repo, or non-zero
86 * Set to 1 if errors validating the remote host's certificate
89 int ignore_cert_errors
;
92 * Whether to use a fetch or copy the object database.
94 git_clone_local_t local
;
97 * The name to be given to the remote that will be
98 * created. The default is "origin".
100 const char *remote_name
;
103 * The name of the branch to checkout. NULL means use the
104 * remote's default branch.
106 const char* checkout_branch
;
109 * The identity used when updating the reflog. NULL means to
110 * use the default signature using the config.
112 git_signature
*signature
;
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}
119 * Initializes a `git_clone_options` with default values. Equivalent to
120 * creating an instance with GIT_CLONE_OPTIONS_INIT.
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.
126 GIT_EXTERN(int) git_clone_init_options(
127 git_clone_options
*opts
,
128 unsigned int version
);
131 * Clone a remote repository.
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()`.
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)
146 GIT_EXTERN(int) git_clone(
147 git_repository
**out
,
149 const char *local_path
,
150 const git_clone_options
*options
);
153 * Clone into a repository
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.
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)
169 GIT_EXTERN(int) git_clone_into(
170 git_repository
*repo
,
172 const git_checkout_options
*co_opts
,
174 const git_signature
*signature
);
177 * Perform a local clone into a repository
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.
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
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)
197 GIT_EXTERN(int) git_clone_local_into(
198 git_repository
*repo
,
200 const git_checkout_options
*co_opts
,
203 const git_signature
*signature
);