include/git2/clone.h

0001 /*
0002  * Copyright (C) the libgit2 contributors. All rights reserved.
0003  *
0004  * This file is part of libgit2, distributed under the GNU GPL v2 with
0005  * a Linking Exception. For full terms see the included COPYING file.
0006  */
0007 #ifndef INCLUDE_git_clone_h__
0008 #define INCLUDE_git_clone_h__
0009
0010 #include "common.h"
0011 #include "types.h"
0012 #include "indexer.h"
0013 #include "checkout.h"
0014 #include "remote.h"
0015 #include "transport.h"
0016
0017
0018 /**
0019  * @file git2/clone.h
0020  * @brief Git cloning routines
0021  * @defgroup git_clone Git cloning routines
0022  * @ingroup Git
0023  * @{
0024  */
0025 GIT_BEGIN_DECL
0026
0027 /**
0028  * Options for bypassing the git-aware transport on clone. Bypassing
0029  * it means that instead of a fetch, libgit2 will copy the object
0030  * database directory instead of figuring out what it needs, which is
0031  * faster. If possible, it will hardlink the files to save space.
0032  */
0033 typedef enum {
0034     /**
0035      * Auto-detect (default), libgit2 will bypass the git-aware
0036      * transport for local paths, but use a normal fetch for
0037      * `file://` urls.
0038      */
0039     GIT_CLONE_LOCAL_AUTO,
0040     /**
0041      * Bypass the git-aware transport even for a `file://` url.
0042      */
0043     GIT_CLONE_LOCAL,
0044     /**
0045      * Do no bypass the git-aware transport
0046      */
0047     GIT_CLONE_NO_LOCAL,
0048     /**
0049      * Bypass the git-aware transport, but do not try to use
0050      * hardlinks.
0051      */
0052     GIT_CLONE_LOCAL_NO_LINKS
0053 } git_clone_local_t;
0054
0055 /**
0056  * The signature of a function matching git_remote_create, with an additional
0057  * void* as a callback payload.
0058  *
0059  * Callers of git_clone may provide a function matching this signature to override
0060  * the remote creation and customization process during a clone operation.
0061  *
0062  * @param out the resulting remote
0063  * @param repo the repository in which to create the remote
0064  * @param name the remote's name
0065  * @param url the remote's url
0066  * @param payload an opaque payload
0067  * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code
0068  */
0069 typedef int GIT_CALLBACK(git_remote_create_cb)(
0070     git_remote **out,
0071     git_repository *repo,
0072     const char *name,
0073     const char *url,
0074     void *payload);
0075
0076 /**
0077  * The signature of a function matching git_repository_init, with an
0078  * additional void * as callback payload.
0079  *
0080  * Callers of git_clone my provide a function matching this signature
0081  * to override the repository creation and customization process
0082  * during a clone operation.
0083  *
0084  * @param out the resulting repository
0085  * @param path path in which to create the repository
0086  * @param bare whether the repository is bare. This is the value from the clone options
0087  * @param payload payload specified by the options
0088  * @return 0, or a negative value to indicate error
0089  */
0090 typedef int GIT_CALLBACK(git_repository_create_cb)(
0091     git_repository **out,
0092     const char *path,
0093     int bare,
0094     void *payload);
0095
0096 /**
0097  * Clone options structure
0098  *
0099  * Initialize with `GIT_CLONE_OPTIONS_INIT`. Alternatively, you can
0100  * use `git_clone_options_init`.
0101  *
0102  */
0103 typedef struct git_clone_options {
0104     unsigned int version;
0105
0106     /**
0107      * These options are passed to the checkout step. To disable
0108      * checkout, set the `checkout_strategy` to
0109      * `GIT_CHECKOUT_NONE`.
0110      */
0111     git_checkout_options checkout_opts;
0112
0113     /**
0114      * Options which control the fetch, including callbacks.
0115      *
0116      * The callbacks are used for reporting fetch progress, and for acquiring
0117      * credentials in the event they are needed.
0118      */
0119     git_fetch_options fetch_opts;
0120
0121     /**
0122      * Set to zero (false) to create a standard repo, or non-zero
0123      * for a bare repo
0124      */
0125     int bare;
0126
0127     /**
0128      * Whether to use a fetch or copy the object database.
0129      */
0130     git_clone_local_t local;
0131
0132     /**
0133      * The name of the branch to checkout. NULL means use the
0134      * remote's default branch.
0135      */
0136     const char *checkout_branch;
0137
0138     /**
0139      * A callback used to create the new repository into which to
0140      * clone. If NULL, the 'bare' field will be used to determine
0141      * whether to create a bare repository.
0142      */
0143     git_repository_create_cb repository_cb;
0144
0145     /**
0146      * An opaque payload to pass to the git_repository creation callback.
0147      * This parameter is ignored unless repository_cb is non-NULL.
0148      */
0149     void *repository_cb_payload;
0150
0151     /**
0152      * A callback used to create the git_remote, prior to its being
0153      * used to perform the clone operation. See the documentation for
0154      * git_remote_create_cb for details. This parameter may be NULL,
0155      * indicating that git_clone should provide default behavior.
0156      */
0157     git_remote_create_cb remote_cb;
0158
0159     /**
0160      * An opaque payload to pass to the git_remote creation callback.
0161      * This parameter is ignored unless remote_cb is non-NULL.
0162      */
0163     void *remote_cb_payload;
0164 } git_clone_options;
0165
0166 #define GIT_CLONE_OPTIONS_VERSION 1
0167 #define GIT_CLONE_OPTIONS_INIT { GIT_CLONE_OPTIONS_VERSION, \
0168     { GIT_CHECKOUT_OPTIONS_VERSION, GIT_CHECKOUT_SAFE }, \
0169     GIT_FETCH_OPTIONS_INIT }
0170
0171 /**
0172  * Initialize git_clone_options structure
0173  *
0174  * Initializes a `git_clone_options` with default values. Equivalent to creating
0175  * an instance with GIT_CLONE_OPTIONS_INIT.
0176  *
0177  * @param opts The `git_clone_options` struct to initialize.
0178  * @param version The struct version; pass `GIT_CLONE_OPTIONS_VERSION`.
0179  * @return Zero on success; -1 on failure.
0180  */
0181 GIT_EXTERN(int) git_clone_options_init(
0182     git_clone_options *opts,
0183     unsigned int version);
0184
0185 /**
0186  * Clone a remote repository.
0187  *
0188  * By default this creates its repository and initial remote to match
0189  * git's defaults. You can use the options in the callback to
0190  * customize how these are created.
0191  *
0192  * @param out pointer that will receive the resulting repository object
0193  * @param url the remote repository to clone
0194  * @param local_path local directory to clone to
0195  * @param options configuration options for the clone.  If NULL, the
0196  *        function works as though GIT_OPTIONS_INIT were passed.
0197  * @return 0 on success, any non-zero return value from a callback
0198  *         function, or a negative value to indicate an error (use
0199  *         `git_error_last` for a detailed error message)
0200  */
0201 GIT_EXTERN(int) git_clone(
0202     git_repository **out,
0203     const char *url,
0204     const char *local_path,
0205     const git_clone_options *options);
0206
0207 /** @} */
0208 GIT_END_DECL
0209 #endif