include/git2/clone.h

   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
  16
  17 /**
  18  * @file git2/clone.h
  19  * @brief Git cloning routines
  20  * @defgroup git_clone Git cloning routines
  21  * @ingroup Git
  22  * @{
  23  */
  24 GIT_BEGIN_DECL
  25
  26 /**
  27  * Clone options structure
  28  *
  29  * Use the GIT_CLONE_OPTIONS_INIT to get the default settings, like this:
  30  *
  31  *              git_clone_options opts = GIT_CLONE_OPTIONS_INIT;
  32  *
  33  * - `checkout_opts` are option passed to the checkout step.  To disable
  34  *   checkout, set the `checkout_strategy` to GIT_CHECKOUT_NONE.
  35  *   Generally you will want the use GIT_CHECKOUT_SAFE_CREATE to create
  36  *   all files in the working directory for the newly cloned repository.
  37  * - `bare` should be set to zero (false) to create a standard repo,
  38  *   or non-zero for a bare repo
  39  * - `ignore_cert_errors` should be set to 1 if errors validating the
  40  *   remote host's certificate should be ignored.
  41  *
  42  *   ** "origin" remote options: **
  43  *
  44  * - `remote_name` is the name to be given to the "origin" remote.  The
  45  *   default is "origin".
  46  * - `checkout_branch` gives the name of the branch to checkout.  NULL
  47  *   means use the remote's HEAD.
  48  * - `signature` is the identity used when updating the reflog. NULL means to
  49  *   use the default signature using the config.
  50  */
  51
  52 typedef struct git_clone_options {
  53         unsigned int version;
  54
  55         git_checkout_opts checkout_opts;
  56         git_remote_callbacks remote_callbacks;
  57
  58         int bare;
  59         int ignore_cert_errors;
  60         const char *remote_name;
  61         const char* checkout_branch;
  62         git_signature *signature;
  63 } git_clone_options;
  64
  65 #define GIT_CLONE_OPTIONS_VERSION 1
  66 #define GIT_CLONE_OPTIONS_INIT {GIT_CLONE_OPTIONS_VERSION, {GIT_CHECKOUT_OPTS_VERSION, GIT_CHECKOUT_SAFE_CREATE}, GIT_REMOTE_CALLBACKS_INIT}
  67
  68 /**
  69 * Initializes a `git_clone_options` with default values. Equivalent to
  70 * creating an instance with GIT_CLONE_OPTIONS_INIT.
  71 *
  72 * @param opts the `git_clone_options` instance to initialize.
  73 * @param version the version of the struct; you should pass
  74 * `GIT_CLONE_OPTIONS_VERSION` here.
  75 * @return Zero on success; -1 on failure.
  76 */
  77 GIT_EXTERN(int) git_clone_init_options(
  78         git_clone_options* opts,
  79         int version);
  80
  81 /**
  82  * Clone a remote repository.
  83  *
  84  * This version handles the simple case. If you'd like to create the
  85  * repository or remote with non-default settings, you can create and
  86  * configure them and then use `git_clone_into()`.
  87  *
  88  * @param out pointer that will receive the resulting repository object
  89  * @param url the remote repository to clone
  90  * @param local_path local directory to clone to
  91  * @param options configuration options for the clone.  If NULL, the
  92  *        function works as though GIT_OPTIONS_INIT were passed.
  93  * @return 0 on success, any non-zero return value from a callback
  94  *         function, or a negative value to indicate an error (use
  95  *         `giterr_last` for a detailed error message)
  96  */
  97 GIT_EXTERN(int) git_clone(
  98         git_repository **out,
  99         const char *url,
 100         const char *local_path,
 101         const git_clone_options *options);
 102
 103 /**
 104  * Clone into a repository
 105  *
 106  * After creating the repository and remote and configuring them for
 107  * paths and callbacks respectively, you can call this function to
 108  * perform the clone operation and optionally checkout files.
 109  *
 110  * @param repo the repository to use
 111  * @param remote the remote repository to clone from
 112  * @param co_opts options to use during checkout
 113  * @param branch the branch to checkout after the clone, pass NULL for the
 114  *        remote's default branch
 115  * @param signature The identity used when updating the reflog.
 116  * @return 0 on success, any non-zero return value from a callback
 117  *         function, or a negative value to indicate an error (use
 118  *         `giterr_last` for a detailed error message)
 119  */
 120 GIT_EXTERN(int) git_clone_into(
 121         git_repository *repo,
 122         git_remote *remote,
 123         const git_checkout_opts *co_opts,
 124         const char *branch,
 125         const git_signature *signature);
 126
 127 /** @} */
 128 GIT_END_DECL
 129 #endif