include/git2/sys/commit_graph.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_sys_git_commit_graph_h__
   8 #define INCLUDE_sys_git_commit_graph_h__
   9
  10 #include "git2/common.h"
  11 #include "git2/types.h"
  12
  13 /**
  14  * @file git2/sys/commit_graph.h
  15  * @brief Git commit-graph
  16  * @defgroup git_commit_graph Git commit-graph APIs
  17  * @ingroup Git
  18  * @{
  19  */
  20 GIT_BEGIN_DECL
  21
  22 /**
  23  * Opens a `git_commit_graph` from a path to an objects directory.
  24  *
  25  * This finds, opens, and validates the `commit-graph` file.
  26  *
  27  * @param cgraph_out the `git_commit_graph` struct to initialize.
  28  * @param objects_dir the path to a git objects directory.
  29  * @return Zero on success; -1 on failure.
  30  */
  31 GIT_EXTERN(int) git_commit_graph_open(git_commit_graph **cgraph_out, const char *objects_dir);
  32
  33 /**
  34  * Frees commit-graph data. This should only be called when memory allocated
  35  * using `git_commit_graph_open` is not returned to libgit2 because it was not
  36  * associated with the ODB through a successful call to
  37  * `git_odb_set_commit_graph`.
  38  *
  39  * @param cgraph the commit-graph object to free. If NULL, no action is taken.
  40  */
  41 GIT_EXTERN(void) git_commit_graph_free(git_commit_graph *cgraph);
  42
  43 /**
  44  * Create a new writer for `commit-graph` files.
  45  *
  46  * @param out Location to store the writer pointer.
  47  * @param objects_info_dir The `objects/info` directory.
  48  * The `commit-graph` file will be written in this directory.
  49  * @return 0 or an error code
  50  */
  51 GIT_EXTERN(int) git_commit_graph_writer_new(
  52                 git_commit_graph_writer **out,
  53                 const char *objects_info_dir);
  54
  55 /**
  56  * Free the commit-graph writer and its resources.
  57  *
  58  * @param w The writer to free. If NULL no action is taken.
  59  */
  60 GIT_EXTERN(void) git_commit_graph_writer_free(git_commit_graph_writer *w);
  61
  62 /**
  63  * Add an `.idx` file (associated to a packfile) to the writer.
  64  *
  65  * @param w The writer.
  66  * @param repo The repository that owns the `.idx` file.
  67  * @param idx_path The path of an `.idx` file.
  68  * @return 0 or an error code
  69  */
  70 GIT_EXTERN(int) git_commit_graph_writer_add_index_file(
  71                 git_commit_graph_writer *w,
  72                 git_repository *repo,
  73                 const char *idx_path);
  74
  75 /**
  76  * Add a revwalk to the writer. This will add all the commits from the revwalk
  77  * to the commit-graph.
  78  *
  79  * @param w The writer.
  80  * @param walk The git_revwalk.
  81  * @return 0 or an error code
  82  */
  83 GIT_EXTERN(int) git_commit_graph_writer_add_revwalk(
  84                 git_commit_graph_writer *w,
  85                 git_revwalk *walk);
  86
  87
  88 /**
  89  * The strategy to use when adding a new set of commits to a pre-existing
  90  * commit-graph chain.
  91  */
  92 typedef enum {
  93         /**
  94          * Do not split commit-graph files. The other split strategy-related option
  95          * fields are ignored.
  96          */
  97         GIT_COMMIT_GRAPH_SPLIT_STRATEGY_SINGLE_FILE = 0,
  98 } git_commit_graph_split_strategy_t;
  99
 100 /**
 101  * Options structure for
 102  * `git_commit_graph_writer_commit`/`git_commit_graph_writer_dump`.
 103  *
 104  * Initialize with `GIT_COMMIT_GRAPH_WRITER_OPTIONS_INIT`. Alternatively, you
 105  * can use `git_commit_graph_writer_options_init`.
 106  */
 107 typedef struct {
 108         unsigned int version;
 109
 110         /**
 111          * The strategy to use when adding new commits to a pre-existing commit-graph
 112          * chain.
 113          */
 114         git_commit_graph_split_strategy_t split_strategy;
 115
 116         /**
 117          * The number of commits in level N is less than X times the number of
 118          * commits in level N + 1. Default is 2.
 119          */
 120         float size_multiple;
 121
 122         /**
 123          * The number of commits in level N + 1 is more than C commits.
 124          * Default is 64000.
 125          */
 126         size_t max_commits;
 127 } git_commit_graph_writer_options;
 128
 129 #define GIT_COMMIT_GRAPH_WRITER_OPTIONS_VERSION 1
 130 #define GIT_COMMIT_GRAPH_WRITER_OPTIONS_INIT { \
 131                 GIT_COMMIT_GRAPH_WRITER_OPTIONS_VERSION \
 132         }
 133
 134 /**
 135  * Initialize git_commit_graph_writer_options structure
 136  *
 137  * Initializes a `git_commit_graph_writer_options` with default values. Equivalent to
 138  * creating an instance with `GIT_COMMIT_GRAPH_WRITER_OPTIONS_INIT`.
 139  *
 140  * @param opts The `git_commit_graph_writer_options` struct to initialize.
 141  * @param version The struct version; pass `GIT_COMMIT_GRAPH_WRITER_OPTIONS_VERSION`.
 142  * @return Zero on success; -1 on failure.
 143  */
 144 GIT_EXTERN(int) git_commit_graph_writer_options_init(
 145         git_commit_graph_writer_options *opts,
 146         unsigned int version);
 147
 148 /**
 149  * Write a `commit-graph` file to a file.
 150  *
 151  * @param w The writer
 152  * @param opts Pointer to git_commit_graph_writer_options struct.
 153  * @return 0 or an error code
 154  */
 155 GIT_EXTERN(int) git_commit_graph_writer_commit(
 156                 git_commit_graph_writer *w,
 157                 git_commit_graph_writer_options *opts);
 158
 159 /**
 160  * Dump the contents of the `commit-graph` to an in-memory buffer.
 161  *
 162  * @param buffer Buffer where to store the contents of the `commit-graph`.
 163  * @param w The writer.
 164  * @param opts Pointer to git_commit_graph_writer_options struct.
 165  * @return 0 or an error code
 166  */
 167 GIT_EXTERN(int) git_commit_graph_writer_dump(
 168                 git_buf *buffer,
 169                 git_commit_graph_writer *w,
 170                 git_commit_graph_writer_options *opts);
 171
 172 /** @} */
 173 GIT_END_DECL
 174 #endif