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__
15 #include "transport.h"
20 * @brief Git cloning routines
21 * @defgroup git_clone Git cloning routines
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.
35 * Auto-detect (default), libgit2 will bypass the git-aware
36 * transport for local paths, but use a normal fetch for
41 * Bypass the git-aware transport even for a `file://` url.
45 * Do no bypass the git-aware transport
49 * Bypass the git-aware transport, but do not try to use
52 GIT_CLONE_LOCAL_NO_LINKS
56 * The signature of a function matching git_remote_create, with an additional
57 * void* as a callback payload.
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.
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
69 typedef int GIT_CALLBACK(git_remote_create_cb
)(
77 * The signature of a function matching git_repository_init, with an
78 * additional void * as callback payload.
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.
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
90 typedef int GIT_CALLBACK(git_repository_create_cb
)(
97 * Clone options structure
99 * Initialize with `GIT_CLONE_OPTIONS_INIT`. Alternatively, you can
100 * use `git_clone_options_init`.
103 typedef struct git_clone_options
{
104 unsigned int version
;
107 * These options are passed to the checkout step. To disable
108 * checkout, set the `checkout_strategy` to
109 * `GIT_CHECKOUT_NONE`.
111 git_checkout_options checkout_opts
;
114 * Options which control the fetch, including callbacks.
116 * The callbacks are used for reporting fetch progress, and for acquiring
117 * credentials in the event they are needed.
119 git_fetch_options fetch_opts
;
122 * Set to zero (false) to create a standard repo, or non-zero
128 * Whether to use a fetch or copy the object database.
130 git_clone_local_t local
;
133 * The name of the branch to checkout. NULL means use the
134 * remote's default branch.
136 const char *checkout_branch
;
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.
143 git_repository_create_cb repository_cb
;
146 * An opaque payload to pass to the git_repository creation callback.
147 * This parameter is ignored unless repository_cb is non-NULL.
149 void *repository_cb_payload
;
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.
157 git_remote_create_cb remote_cb
;
160 * An opaque payload to pass to the git_remote creation callback.
161 * This parameter is ignored unless remote_cb is non-NULL.
163 void *remote_cb_payload
;
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 }
172 * Initialize git_clone_options structure
174 * Initializes a `git_clone_options` with default values. Equivalent to creating
175 * an instance with GIT_CLONE_OPTIONS_INIT.
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.
181 GIT_EXTERN(int) git_clone_options_init(
182 git_clone_options
*opts
,
183 unsigned int version
);
186 * Clone a remote repository.
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.
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)
201 GIT_EXTERN(int) git_clone(
202 git_repository
**out
,
204 const char *local_path
,
205 const git_clone_options
*options
);