include/git2/types.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_types_h__
   8 #define INCLUDE_git_types_h__
   9
  10 #include "common.h"
  11
  12 /**
  13  * @file git2/types.h
  14  * @brief libgit2 base & compatibility types
  15  * @ingroup Git
  16  * @{
  17  */
  18 GIT_BEGIN_DECL
  19
  20 /**
  21  * Cross-platform compatibility types for off_t / time_t
  22  *
  23  * NOTE: This needs to be in a public header so that both the library
  24  * implementation and client applications both agree on the same types.
  25  * Otherwise we get undefined behavior.
  26  *
  27  * Use the "best" types that each platform provides. Currently we truncate
  28  * these intermediate representations for compatibility with the git ABI, but
  29  * if and when it changes to support 64 bit types, our code will naturally
  30  * adapt.
  31  * NOTE: These types should match those that are returned by our internal
  32  * stat() functions, for all platforms.
  33  */
  34 #include <sys/types.h>
  35 #ifdef __amigaos4__
  36 #include <stdint.h>
  37 #endif
  38
  39 #if defined(_MSC_VER)
  40
  41 typedef __int64 git_off_t;
  42 typedef __time64_t git_time_t;
  43
  44 #elif defined(__MINGW32__)
  45
  46 typedef off64_t git_off_t;
  47 typedef __time64_t git_time_t;
  48
  49 #elif defined(__HAIKU__)
  50
  51 typedef __haiku_std_int64 git_off_t;
  52 typedef __haiku_std_int64 git_time_t;
  53
  54 #else /* POSIX */
  55
  56 /*
  57  * Note: Can't use off_t since if a client program includes <sys/types.h>
  58  * before us (directly or indirectly), they'll get 32 bit off_t in their client
  59  * app, even though /we/ define _FILE_OFFSET_BITS=64.
  60  */
  61 typedef int64_t git_off_t;
  62 typedef int64_t git_time_t;
  63
  64 #endif
  65
  66 /** Basic type (loose or packed) of any Git object. */
  67 typedef enum {
  68         GIT_OBJ_ANY = -2,               /**< Object can be any of the following */
  69         GIT_OBJ_BAD = -1,               /**< Object is invalid. */
  70         GIT_OBJ__EXT1 = 0,              /**< Reserved for future use. */
  71         GIT_OBJ_COMMIT = 1,             /**< A commit object. */
  72         GIT_OBJ_TREE = 2,               /**< A tree (directory listing) object. */
  73         GIT_OBJ_BLOB = 3,               /**< A file revision object. */
  74         GIT_OBJ_TAG = 4,                /**< An annotated tag object. */
  75         GIT_OBJ__EXT2 = 5,              /**< Reserved for future use. */
  76         GIT_OBJ_OFS_DELTA = 6, /**< A delta, base is given by an offset. */
  77         GIT_OBJ_REF_DELTA = 7, /**< A delta, base is given by object id. */
  78 } git_otype;
  79
  80 /** An open object database handle. */
  81 typedef struct git_odb git_odb;
  82
  83 /** A custom backend in an ODB */
  84 typedef struct git_odb_backend git_odb_backend;
  85
  86 /** An object read from the ODB */
  87 typedef struct git_odb_object git_odb_object;
  88
  89 /** A stream to read/write from the ODB */
  90 typedef struct git_odb_stream git_odb_stream;
  91
  92 /** A stream to write a packfile to the ODB */
  93 typedef struct git_odb_writepack git_odb_writepack;
  94
  95 /** An open refs database handle. */
  96 typedef struct git_refdb git_refdb;
  97
  98 /** A custom backend for refs */
  99 typedef struct git_refdb_backend git_refdb_backend;
 100
 101 /**
 102  * Representation of an existing git repository,
 103  * including all its object contents
 104  */
 105 typedef struct git_repository git_repository;
 106
 107 /** Representation of a generic object in a repository */
 108 typedef struct git_object git_object;
 109
 110 /** Representation of an in-progress walk through the commits in a repo */
 111 typedef struct git_revwalk git_revwalk;
 112
 113 /** Parsed representation of a tag object. */
 114 typedef struct git_tag git_tag;
 115
 116 /** In-memory representation of a blob object. */
 117 typedef struct git_blob git_blob;
 118
 119 /** Parsed representation of a commit object. */
 120 typedef struct git_commit git_commit;
 121
 122 /** Representation of each one of the entries in a tree object. */
 123 typedef struct git_tree_entry git_tree_entry;
 124
 125 /** Representation of a tree object. */
 126 typedef struct git_tree git_tree;
 127
 128 /** Constructor for in-memory trees */
 129 typedef struct git_treebuilder git_treebuilder;
 130
 131 /** Memory representation of an index file. */
 132 typedef struct git_index git_index;
 133
 134 /** An iterator for conflicts in the index. */
 135 typedef struct git_index_conflict_iterator git_index_conflict_iterator;
 136
 137 /** Memory representation of a set of config files */
 138 typedef struct git_config git_config;
 139
 140 /** Interface to access a configuration file */
 141 typedef struct git_config_backend git_config_backend;
 142
 143 /** Representation of a reference log entry */
 144 typedef struct git_reflog_entry git_reflog_entry;
 145
 146 /** Representation of a reference log */
 147 typedef struct git_reflog git_reflog;
 148
 149 /** Representation of a git note */
 150 typedef struct git_note git_note;
 151
 152 /** Representation of a git packbuilder */
 153 typedef struct git_packbuilder git_packbuilder;
 154
 155 /** Time in a signature */
 156 typedef struct git_time {
 157         git_time_t time; /**< time in seconds from epoch */
 158         int offset; /**< timezone offset, in minutes */
 159 } git_time;
 160
 161 /** An action signature (e.g. for committers, taggers, etc) */
 162 typedef struct git_signature {
 163         char *name; /**< full name of the author */
 164         char *email; /**< email of the author */
 165         git_time when; /**< time when the action happened */
 166 } git_signature;
 167
 168 /** In-memory representation of a reference. */
 169 typedef struct git_reference git_reference;
 170
 171 /** Iterator for references */
 172 typedef struct git_reference_iterator  git_reference_iterator;
 173
 174 /** Transactional interface to references */
 175 typedef struct git_transaction git_transaction;
 176
 177 /** Annotated commits, the input to merge and rebase. */
 178 typedef struct git_annotated_commit git_annotated_commit;
 179
 180 /** Merge result */
 181 typedef struct git_merge_result git_merge_result;
 182
 183 /** Representation of a status collection */
 184 typedef struct git_status_list git_status_list;
 185
 186 /** Representation of a rebase */
 187 typedef struct git_rebase git_rebase;
 188
 189 /** Basic type of any Git reference. */
 190 typedef enum {
 191         GIT_REF_INVALID = 0, /**< Invalid reference */
 192         GIT_REF_OID = 1, /**< A reference which points at an object id */
 193         GIT_REF_SYMBOLIC = 2, /**< A reference which points at another reference */
 194         GIT_REF_LISTALL = GIT_REF_OID|GIT_REF_SYMBOLIC,
 195 } git_ref_t;
 196
 197 /** Basic type of any Git branch. */
 198 typedef enum {
 199         GIT_BRANCH_LOCAL = 1,
 200         GIT_BRANCH_REMOTE = 2,
 201         GIT_BRANCH_ALL = GIT_BRANCH_LOCAL|GIT_BRANCH_REMOTE,
 202 } git_branch_t;
 203
 204 /** Valid modes for index and tree entries. */
 205 typedef enum {
 206         GIT_FILEMODE_UNREADABLE          = 0000000,
 207         GIT_FILEMODE_TREE                = 0040000,
 208         GIT_FILEMODE_BLOB                = 0100644,
 209         GIT_FILEMODE_BLOB_EXECUTABLE     = 0100755,
 210         GIT_FILEMODE_LINK                = 0120000,
 211         GIT_FILEMODE_COMMIT              = 0160000,
 212 } git_filemode_t;
 213
 214 /*
 215  * A refspec specifies the mapping between remote and local reference
 216  * names when fetch or pushing.
 217  */
 218 typedef struct git_refspec git_refspec;
 219
 220 /**
 221  * Git's idea of a remote repository. A remote can be anonymous (in
 222  * which case it does not have backing configuration entires).
 223  */
 224 typedef struct git_remote git_remote;
 225
 226 /**
 227  * Interface which represents a transport to communicate with a
 228  * remote.
 229  */
 230 typedef struct git_transport git_transport;
 231
 232 /**
 233  * Preparation for a push operation. Can be used to configure what to
 234  * push and the level of parallelism of the packfile builder.
 235  */
 236 typedef struct git_push git_push;
 237
 238 /* documentation in the definition */
 239 typedef struct git_remote_head git_remote_head;
 240 typedef struct git_remote_callbacks git_remote_callbacks;
 241
 242 /**
 243  * This is passed as the first argument to the callback to allow the
 244  * user to see the progress.
 245  *
 246  * - total_objects: number of objects in the packfile being downloaded
 247  * - indexed_objects: received objects that have been hashed
 248  * - received_objects: objects which have been downloaded
 249  * - local_objects: locally-available objects that have been injected
 250  *    in order to fix a thin pack.
 251  * - received-bytes: size of the packfile received up to now
 252  */
 253 typedef struct git_transfer_progress {
 254         unsigned int total_objects;
 255         unsigned int indexed_objects;
 256         unsigned int received_objects;
 257         unsigned int local_objects;
 258         unsigned int total_deltas;
 259         unsigned int indexed_deltas;
 260         size_t received_bytes;
 261 } git_transfer_progress;
 262
 263 /**
 264  * Type for progress callbacks during indexing.  Return a value less than zero
 265  * to cancel the transfer.
 266  *
 267  * @param stats Structure containing information about the state of the transfer
 268  * @param payload Payload provided by caller
 269  */
 270 typedef int (*git_transfer_progress_cb)(const git_transfer_progress *stats, void *payload);
 271
 272 /**
 273  * Type for messages delivered by the transport.  Return a negative value
 274  * to cancel the network operation.
 275  *
 276  * @param str The message from the transport
 277  * @param len The length of the message
 278  * @param payload Payload provided by the caller
 279  */
 280 typedef int (*git_transport_message_cb)(const char *str, int len, void *payload);
 281
 282
 283 /**
 284  * Type of host certificate structure that is passed to the check callback
 285  */
 286 typedef enum git_cert_t {
 287         /**
 288          * No information about the certificate is available. This may
 289          * happen when using curl.
 290          */
 291         GIT_CERT_NONE,
 292         /**
 293          * The `data` argument to the callback will be a pointer to
 294          * the DER-encoded data.
 295          */
 296         GIT_CERT_X509,
 297         /**
 298          * The `data` argument to the callback will be a pointer to a
 299          * `git_cert_hostkey` structure.
 300          */
 301         GIT_CERT_HOSTKEY_LIBSSH2,
 302         /**
 303          * The `data` argument to the callback will be a pointer to a
 304          * `git_strarray` with `name:content` strings containing
 305          * information about the certificate. This is used when using
 306          * curl.
 307          */
 308         GIT_CERT_STRARRAY,
 309 } git_cert_t;
 310
 311 /**
 312  * Parent type for `git_cert_hostkey` and `git_cert_x509`.
 313  */
 314 typedef struct {
 315         /**
 316          * Type of certificate. A `GIT_CERT_` value.
 317          */
 318         git_cert_t cert_type;
 319 } git_cert;
 320
 321 /**
 322  * Callback for the user's custom certificate checks.
 323  *
 324  * @param cert The host certificate
 325  * @param valid Whether the libgit2 checks (OpenSSL or WinHTTP) think
 326  * this certificate is valid
 327  * @param host Hostname of the host libgit2 connected to
 328  * @param payload Payload provided by the caller
 329  */
 330 typedef int (*git_transport_certificate_check_cb)(git_cert *cert, int valid, const char *host, void *payload);
 331
 332 /**
 333  * Opaque structure representing a submodule.
 334  */
 335 typedef struct git_submodule git_submodule;
 336
 337 /**
 338  * Submodule update values
 339  *
 340  * These values represent settings for the `submodule.$name.update`
 341  * configuration value which says how to handle `git submodule update` for
 342  * this submodule.  The value is usually set in the ".gitmodules" file and
 343  * copied to ".git/config" when the submodule is initialized.
 344  *
 345  * You can override this setting on a per-submodule basis with
 346  * `git_submodule_set_update()` and write the changed value to disk using
 347  * `git_submodule_save()`.  If you have overwritten the value, you can
 348  * revert it by passing `GIT_SUBMODULE_UPDATE_RESET` to the set function.
 349  *
 350  * The values are:
 351  *
 352  * - GIT_SUBMODULE_UPDATE_RESET: reset to the on-disk value.
 353  * - GIT_SUBMODULE_UPDATE_CHECKOUT: the default; when a submodule is
 354  *   updated, checkout the new detached HEAD to the submodule directory.
 355  * - GIT_SUBMODULE_UPDATE_REBASE: update by rebasing the current checked
 356  *   out branch onto the commit from the superproject.
 357  * - GIT_SUBMODULE_UPDATE_MERGE: update by merging the commit in the
 358  *   superproject into the current checkout out branch of the submodule.
 359  * - GIT_SUBMODULE_UPDATE_NONE: do not update this submodule even when
 360  *   the commit in the superproject is updated.
 361  * - GIT_SUBMODULE_UPDATE_DEFAULT: not used except as static initializer
 362  *   when we don't want any particular update rule to be specified.
 363  */
 364 typedef enum {
 365         GIT_SUBMODULE_UPDATE_RESET    = -1,
 366
 367         GIT_SUBMODULE_UPDATE_CHECKOUT = 1,
 368         GIT_SUBMODULE_UPDATE_REBASE   = 2,
 369         GIT_SUBMODULE_UPDATE_MERGE    = 3,
 370         GIT_SUBMODULE_UPDATE_NONE     = 4,
 371
 372         GIT_SUBMODULE_UPDATE_DEFAULT  = 0
 373 } git_submodule_update_t;
 374
 375 /**
 376  * Submodule ignore values
 377  *
 378  * These values represent settings for the `submodule.$name.ignore`
 379  * configuration value which says how deeply to look at the working
 380  * directory when getting submodule status.
 381  *
 382  * You can override this value in memory on a per-submodule basis with
 383  * `git_submodule_set_ignore()` and can write the changed value to disk
 384  * with `git_submodule_save()`.  If you have overwritten the value, you
 385  * can revert to the on disk value by using `GIT_SUBMODULE_IGNORE_RESET`.
 386  *
 387  * The values are:
 388  *
 389  * - GIT_SUBMODULE_IGNORE_RESET: reset to the on-disk value.
 390  * - GIT_SUBMODULE_IGNORE_NONE: don't ignore any change - i.e. even an
 391  *   untracked file, will mark the submodule as dirty.  Ignored files are
 392  *   still ignored, of course.
 393  * - GIT_SUBMODULE_IGNORE_UNTRACKED: ignore untracked files; only changes
 394  *   to tracked files, or the index or the HEAD commit will matter.
 395  * - GIT_SUBMODULE_IGNORE_DIRTY: ignore changes in the working directory,
 396  *   only considering changes if the HEAD of submodule has moved from the
 397  *   value in the superproject.
 398  * - GIT_SUBMODULE_IGNORE_ALL: never check if the submodule is dirty
 399  * - GIT_SUBMODULE_IGNORE_DEFAULT: not used except as static initializer
 400  *   when we don't want any particular ignore rule to be specified.
 401  */
 402 typedef enum {
 403         GIT_SUBMODULE_IGNORE_RESET     = -1, /**< reset to on-disk value */
 404
 405         GIT_SUBMODULE_IGNORE_NONE      = 1,  /**< any change or untracked == dirty */
 406         GIT_SUBMODULE_IGNORE_UNTRACKED = 2,  /**< dirty if tracked files change */
 407         GIT_SUBMODULE_IGNORE_DIRTY     = 3,  /**< only dirty if HEAD moved */
 408         GIT_SUBMODULE_IGNORE_ALL       = 4,  /**< never dirty */
 409
 410         GIT_SUBMODULE_IGNORE_DEFAULT   = 0
 411 } git_submodule_ignore_t;
 412
 413 /**
 414  * Options for submodule recurse.
 415  *
 416  * Represent the value of `submodule.$name.fetchRecurseSubmodules`
 417  *
 418  * * GIT_SUBMODULE_RECURSE_RESET - reset to the on-disk value
 419  * * GIT_SUBMODULE_RECURSE_NO    - do no recurse into submodules
 420  * * GIT_SUBMODULE_RECURSE_YES   - recurse into submodules
 421  * * GIT_SUBMODULE_RECURSE_ONDEMAND - recurse into submodules only when
 422  *                                    commit not already in local clone
 423  */
 424 typedef enum {
 425         GIT_SUBMODULE_RECURSE_RESET = -1,
 426
 427         GIT_SUBMODULE_RECURSE_NO = 0,
 428         GIT_SUBMODULE_RECURSE_YES = 1,
 429         GIT_SUBMODULE_RECURSE_ONDEMAND = 2,
 430 } git_submodule_recurse_t;
 431
 432 /** A type to write in a streaming fashion, for example, for filters. */
 433 typedef struct git_writestream git_writestream;
 434
 435 struct git_writestream {
 436         int (*write)(git_writestream *stream, const char *buffer, size_t len);
 437         int (*close)(git_writestream *stream);
 438         void (*free)(git_writestream *stream);
 439 };
 440
 441 /** @} */
 442 GIT_END_DECL
 443
 444 #endif