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_remote_create_cb
)(
77 * The signature of a function matchin git_repository_init, with an
78 * aditional 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_repository_create_cb
)(
97 * Clone options structure
99 * Use the GIT_CLONE_OPTIONS_INIT to get the default settings, like this:
101 * git_clone_options opts = 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 * Callbacks to use for reporting fetch progress, and for acquiring
115 * credentials in the event they are needed. This parameter is ignored if
116 * the remote_cb parameter is set; if you provide a remote creation
117 * callback, then you have the opportunity to configure remote callbacks in
120 git_remote_callbacks remote_callbacks
;
123 * Set to zero (false) to create a standard repo, or non-zero
129 * Whether to use a fetch or copy the object database.
131 git_clone_local_t local
;
134 * The name of the branch to checkout. NULL means use the
135 * remote's default branch.
137 const char* checkout_branch
;
140 * A callback used to create the new repository into which to
141 * clone. If NULL, the 'bare' field will be used to determine
142 * whether to create a bare repository.
144 git_repository_create_cb repository_cb
;
147 * An opaque payload to pass to the git_repository creation callback.
148 * This parameter is ignored unless repository_cb is non-NULL.
150 void *repository_cb_payload
;
153 * A callback used to create the git_remote, prior to its being
154 * used to perform the clone operation. See the documentation for
155 * git_remote_create_cb for details. This parameter may be NULL,
156 * indicating that git_clone should provide default behavior.
158 git_remote_create_cb remote_cb
;
161 * An opaque payload to pass to the git_remote creation callback.
162 * This parameter is ignored unless remote_cb is non-NULL.
164 void *remote_cb_payload
;
167 #define GIT_CLONE_OPTIONS_VERSION 1
168 #define GIT_CLONE_OPTIONS_INIT { GIT_CLONE_OPTIONS_VERSION, \
169 { GIT_CHECKOUT_OPTIONS_VERSION, GIT_CHECKOUT_SAFE }, \
170 GIT_REMOTE_CALLBACKS_INIT }
173 * Initializes a `git_clone_options` with default values. Equivalent to
174 * creating an instance with GIT_CLONE_OPTIONS_INIT.
176 * @param opts The `git_clone_options` struct to initialize
177 * @param version Version of struct; pass `GIT_CLONE_OPTIONS_VERSION`
178 * @return Zero on success; -1 on failure.
180 GIT_EXTERN(int) git_clone_init_options(
181 git_clone_options
*opts
,
182 unsigned int version
);
185 * Clone a remote repository.
187 * By default this creates its repository and initial remote to match
188 * git's defaults. You can use the options in the callback to
189 * customize how these are created.
191 * @param out pointer that will receive the resulting repository object
192 * @param url the remote repository to clone
193 * @param local_path local directory to clone to
194 * @param options configuration options for the clone. If NULL, the
195 * function works as though GIT_OPTIONS_INIT were passed.
196 * @return 0 on success, any non-zero return value from a callback
197 * function, or a negative value to indicate an error (use
198 * `giterr_last` for a detailed error message)
200 GIT_EXTERN(int) git_clone(
201 git_repository
**out
,
203 const char *local_path
,
204 const git_clone_options
*options
);