include/git2/index.h

   1 /*
   2  * Copyright (C) 2009-2012 the libgit2 contributors
   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_index_h__
   8 #define INCLUDE_git_index_h__
   9
  10 #include "common.h"
  11 #include "indexer.h"
  12 #include "types.h"
  13 #include "oid.h"
  14
  15 /**
  16  * @file git2/index.h
  17  * @brief Git index parsing and manipulation routines
  18  * @defgroup git_index Git index parsing and manipulation routines
  19  * @ingroup Git
  20  * @{
  21  */
  22 GIT_BEGIN_DECL
  23
  24 #define GIT_IDXENTRY_NAMEMASK  (0x0fff)
  25 #define GIT_IDXENTRY_STAGEMASK (0x3000)
  26 #define GIT_IDXENTRY_EXTENDED  (0x4000)
  27 #define GIT_IDXENTRY_VALID     (0x8000)
  28 #define GIT_IDXENTRY_STAGESHIFT 12
  29
  30 /*
  31  * Flags are divided into two parts: in-memory flags and
  32  * on-disk ones. Flags in GIT_IDXENTRY_EXTENDED_FLAGS
  33  * will get saved on-disk.
  34  *
  35  * In-memory only flags:
  36  */
  37 #define GIT_IDXENTRY_UPDATE            (1 << 0)
  38 #define GIT_IDXENTRY_REMOVE            (1 << 1)
  39 #define GIT_IDXENTRY_UPTODATE          (1 << 2)
  40 #define GIT_IDXENTRY_ADDED             (1 << 3)
  41
  42 #define GIT_IDXENTRY_HASHED            (1 << 4)
  43 #define GIT_IDXENTRY_UNHASHED          (1 << 5)
  44 #define GIT_IDXENTRY_WT_REMOVE         (1 << 6) /* remove in work directory */
  45 #define GIT_IDXENTRY_CONFLICTED        (1 << 7)
  46
  47 #define GIT_IDXENTRY_UNPACKED          (1 << 8)
  48 #define GIT_IDXENTRY_NEW_SKIP_WORKTREE (1 << 9)
  49
  50 /*
  51  * Extended on-disk flags:
  52  */
  53 #define GIT_IDXENTRY_INTENT_TO_ADD     (1 << 13)
  54 #define GIT_IDXENTRY_SKIP_WORKTREE     (1 << 14)
  55 /* GIT_IDXENTRY_EXTENDED2 is for future extension */
  56 #define GIT_IDXENTRY_EXTENDED2         (1 << 15)
  57
  58 #define GIT_IDXENTRY_EXTENDED_FLAGS (GIT_IDXENTRY_INTENT_TO_ADD | GIT_IDXENTRY_SKIP_WORKTREE)
  59
  60 /** Time used in a git index entry */
  61 typedef struct {
  62         git_time_t seconds;
  63         /* nsec should not be stored as time_t compatible */
  64         unsigned int nanoseconds;
  65 } git_index_time;
  66
  67 /** Memory representation of a file entry in the index. */
  68 typedef struct git_index_entry {
  69         git_index_time ctime;
  70         git_index_time mtime;
  71
  72         unsigned int dev;
  73         unsigned int ino;
  74         unsigned int mode;
  75         unsigned int uid;
  76         unsigned int gid;
  77         git_off_t file_size;
  78
  79         git_oid oid;
  80
  81         unsigned short flags;
  82         unsigned short flags_extended;
  83
  84         char *path;
  85 } git_index_entry;
  86
  87 /** Representation of a resolve undo entry in the index. */
  88 typedef struct git_index_reuc_entry {
  89         unsigned int mode[3];
  90         git_oid oid[3];
  91         char *path;
  92 } git_index_reuc_entry;
  93
  94 /** Capabilities of system that affect index actions. */
  95 enum {
  96         GIT_INDEXCAP_IGNORE_CASE = 1,
  97         GIT_INDEXCAP_NO_FILEMODE = 2,
  98         GIT_INDEXCAP_NO_SYMLINKS = 4,
  99         GIT_INDEXCAP_FROM_OWNER  = ~0u
 100 };
 101
 102 /** @name Index File Functions
 103  *
 104  * These functions work on the index file itself.
 105  */
 106 /**@{*/
 107
 108 /**
 109  * Create a new bare Git index object as a memory representation
 110  * of the Git index file in 'index_path', without a repository
 111  * to back it.
 112  *
 113  * Since there is no ODB or working directory behind this index,
 114  * any Index methods which rely on these (e.g. index_add) will
 115  * fail with the GIT_EBAREINDEX error code.
 116  *
 117  * If you need to access the index of an actual repository,
 118  * use the `git_repository_index` wrapper.
 119  *
 120  * The index must be freed once it's no longer in use.
 121  *
 122  * @param out the pointer for the new index
 123  * @param index_path the path to the index file in disk
 124  * @return 0 or an error code
 125  */
 126 GIT_EXTERN(int) git_index_open(git_index **out, const char *index_path);
 127
 128 /**
 129  * Create an in-memory index object.
 130  *
 131  * This index object cannot be read/written to the filesystem,
 132  * but may be used to perform in-memory index operations.
 133  *
 134  * The index must be freed once it's no longer in use.
 135  *
 136  * @param out the pointer for the new index
 137  * @return 0 or an error code
 138  */
 139 GIT_EXTERN(int) git_index_new(git_index **out);
 140
 141 /**
 142  * Free an existing index object.
 143  *
 144  * @param index an existing index object
 145  */
 146 GIT_EXTERN(void) git_index_free(git_index *index);
 147
 148 /**
 149  * Get the repository this index relates to
 150  *
 151  * @param index The index
 152  * @return A pointer to the repository
 153  */
 154 GIT_EXTERN(git_repository *) git_index_owner(const git_index *index);
 155
 156 /**
 157  * Read index capabilities flags.
 158  *
 159  * @param index An existing index object
 160  * @return A combination of GIT_INDEXCAP values
 161  */
 162 GIT_EXTERN(unsigned int) git_index_caps(const git_index *index);
 163
 164 /**
 165  * Set index capabilities flags.
 166  *
 167  * If you pass `GIT_INDEXCAP_FROM_OWNER` for the caps, then the
 168  * capabilities will be read from the config of the owner object,
 169  * looking at `core.ignorecase`, `core.filemode`, `core.symlinks`.
 170  *
 171  * @param index An existing index object
 172  * @param caps A combination of GIT_INDEXCAP values
 173  * @return 0 on success, -1 on failure
 174  */
 175 GIT_EXTERN(int) git_index_set_caps(git_index *index, unsigned int caps);
 176
 177 /**
 178  * Update the contents of an existing index object in memory
 179  * by reading from the hard disk.
 180  *
 181  * @param index an existing index object
 182  * @return 0 or an error code
 183  */
 184 GIT_EXTERN(int) git_index_read(git_index *index);
 185
 186 /**
 187  * Write an existing index object from memory back to disk
 188  * using an atomic file lock.
 189  *
 190  * @param index an existing index object
 191  * @return 0 or an error code
 192  */
 193 GIT_EXTERN(int) git_index_write(git_index *index);
 194
 195 /**
 196  * Read a tree into the index file with stats
 197  *
 198  * The current index contents will be replaced by the specified tree.
 199  *
 200  * @param index an existing index object
 201  * @param tree tree to read
 202  * @return 0 or an error code
 203  */
 204 GIT_EXTERN(int) git_index_read_tree(git_index *index, const git_tree *tree);
 205
 206 /**
 207  * Write the index as a tree
 208  *
 209  * This method will scan the index and write a representation
 210  * of its current state back to disk; it recursively creates
 211  * tree objects for each of the subtrees stored in the index,
 212  * but only returns the OID of the root tree. This is the OID
 213  * that can be used e.g. to create a commit.
 214  *
 215  * The index instance cannot be bare, and needs to be associated
 216  * to an existing repository.
 217  *
 218  * The index must not contain any file in conflict.
 219  *
 220  * @param out Pointer where to store the OID of the written tree
 221  * @param index Index to write
 222  * @return 0 on success, GIT_EUNMERGED when the index is not clean
 223  * or an error code
 224  */
 225 GIT_EXTERN(int) git_index_write_tree(git_oid *out, git_index *index);
 226
 227 /**
 228  * Write the index as a tree to the given repository
 229  *
 230  * This method will do the same as `git_index_write_tree`, but
 231  * letting the user choose the repository where the tree will
 232  * be written.
 233  *
 234  * The index must not contain any file in conflict.
 235  *
 236  * @param out Pointer where to store OID of the the written tree
 237  * @param index Index to write
 238  * @param repo Repository where to write the tree
 239  * @return 0 on success, GIT_EUNMERGED when the index is not clean
 240  * or an error code
 241  */
 242 GIT_EXTERN(int) git_index_write_tree_to(git_oid *out, git_index *index, git_repository *repo);
 243
 244 /**@}*/
 245
 246 /** @name Raw Index Entry Functions
 247  *
 248  * These functions work on index entries, and allow for raw manipulation
 249  * of the entries.
 250  */
 251 /**@{*/
 252
 253 /* Index entry manipulation */
 254
 255 /**
 256  * Get the count of entries currently in the index
 257  *
 258  * @param index an existing index object
 259  * @return integer of count of current entries
 260  */
 261 GIT_EXTERN(size_t) git_index_entrycount(const git_index *index);
 262
 263 /**
 264  * Clear the contents (all the entries) of an index object.
 265  * This clears the index object in memory; changes must be manually
 266  * written to disk for them to take effect.
 267  *
 268  * @param index an existing index object
 269  */
 270 GIT_EXTERN(void) git_index_clear(git_index *index);
 271
 272 /**
 273  * Get a pointer to one of the entries in the index
 274  *
 275  * The values of this entry can be modified (except the path)
 276  * and the changes will be written back to disk on the next
 277  * write() call.
 278  *
 279  * The entry should not be freed by the caller.
 280  *
 281  * @param index an existing index object
 282  * @param n the position of the entry
 283  * @return a pointer to the entry; NULL if out of bounds
 284  */
 285 GIT_EXTERN(const git_index_entry *) git_index_get_byindex(
 286         git_index *index, size_t n);
 287
 288 /**
 289  * Get a pointer to one of the entries in the index
 290  *
 291  * The values of this entry can be modified (except the path)
 292  * and the changes will be written back to disk on the next
 293  * write() call.
 294  *
 295  * The entry should not be freed by the caller.
 296  *
 297  * @param index an existing index object
 298  * @param path path to search
 299  * @param stage stage to search
 300  * @return a pointer to the entry; NULL if it was not found
 301  */
 302 GIT_EXTERN(const git_index_entry *) git_index_get_bypath(
 303         git_index *index, const char *path, int stage);
 304
 305 /**
 306  * Remove an entry from the index
 307  *
 308  * @param index an existing index object
 309  * @param path path to search
 310  * @param stage stage to search
 311  * @return 0 or an error code
 312  */
 313 GIT_EXTERN(int) git_index_remove(git_index *index, const char *path, int stage);
 314
 315 /**
 316  * Remove all entries from the index under a given directory
 317  *
 318  * @param index an existing index object
 319  * @param dir container directory path
 320  * @param stage stage to search
 321  * @return 0 or an error code
 322  */
 323 GIT_EXTERN(int) git_index_remove_directory(
 324         git_index *index, const char *dir, int stage);
 325
 326 /**
 327  * Add or update an index entry from an in-memory struct
 328  *
 329  * If a previous index entry exists that has the same path and stage
 330  * as the given 'source_entry', it will be replaced.  Otherwise, the
 331  * 'source_entry' will be added.
 332  *
 333  * A full copy (including the 'path' string) of the given
 334  * 'source_entry' will be inserted on the index.
 335  *
 336  * @param index an existing index object
 337  * @param source_entry new entry object
 338  * @return 0 or an error code
 339  */
 340 GIT_EXTERN(int) git_index_add(git_index *index, const git_index_entry *source_entry);
 341
 342 /**
 343  * Return the stage number from a git index entry
 344  *
 345  * This entry is calculated from the entry's flag
 346  * attribute like this:
 347  *
 348  *      (entry->flags & GIT_IDXENTRY_STAGEMASK) >> GIT_IDXENTRY_STAGESHIFT
 349  *
 350  * @param entry The entry
 351  * @returns the stage number
 352  */
 353 GIT_EXTERN(int) git_index_entry_stage(const git_index_entry *entry);
 354
 355 /**@}*/
 356
 357 /** @name Workdir Index Entry Functions
 358  *
 359  * These functions work on index entries specifically in the working
 360  * directory (ie, stage 0).
 361  */
 362 /**@{*/
 363
 364 /**
 365  * Add or update an index entry from a file in disk
 366  *
 367  * The file `path` must be relative to the repository's
 368  * working folder and must be readable.
 369  *
 370  * This method will fail in bare index instances.
 371  *
 372  * This forces the file to be added to the index, not looking
 373  * at gitignore rules.  Those rules can be evaluated through
 374  * the git_status APIs (in status.h) before calling this.
 375  *
 376  * If this file currently is the result of a merge conflict, this
 377  * file will no longer be marked as conflicting.  The data about
 378  * the conflict will be moved to the "resolve undo" (REUC) section.
 379  *
 380  * @param index an existing index object
 381  * @param path filename to add
 382  * @return 0 or an error code
 383  */
 384 GIT_EXTERN(int) git_index_add_from_workdir(git_index *index, const char *path);
 385
 386 /**
 387  * Find the first index of any entries which point to given
 388  * path in the Git index.
 389  *
 390  * @param index an existing index object
 391  * @param path path to search
 392  * @return an index >= 0 if found, -1 otherwise
 393  */
 394 GIT_EXTERN(int) git_index_find(git_index *index, const char *path);
 395
 396 /**@}*/
 397
 398 /** @name Conflict Index Entry Functions
 399  *
 400  * These functions work on conflict index entries specifically (ie, stages 1-3)
 401  */
 402 /**@{*/
 403
 404 /**
 405  * Add or update index entries to represent a conflict
 406  *
 407  * The entries are the entries from the tree included in the merge.  Any
 408  * entry may be null to indicate that that file was not present in the
 409  * trees during the merge.  For example, ancestor_entry may be NULL to
 410  * indicate that a file was added in both branches and must be resolved.
 411  *
 412  * @param index an existing index object
 413  * @param ancestor_entry the entry data for the ancestor of the conflict
 414  * @param our_entry the entry data for our side of the merge conflict
 415  * @param their_entry the entry data for their side of the merge conflict
 416  * @return 0 or an error code
 417  */
 418 GIT_EXTERN(int) git_index_conflict_add(
 419    git_index *index,
 420         const git_index_entry *ancestor_entry,
 421         const git_index_entry *our_entry,
 422         const git_index_entry *their_entry);
 423
 424 /**
 425  * Get the index entries that represent a conflict of a single file.
 426  *
 427  * The values of this entry can be modified (except the paths)
 428  * and the changes will be written back to disk on the next
 429  * write() call.
 430  *
 431  * @param ancestor_out Pointer to store the ancestor entry
 432  * @param our_out Pointer to store the our entry
 433  * @param their_out Pointer to store the their entry
 434  * @param index an existing index object
 435  * @param path path to search
 436  */
 437 GIT_EXTERN(int) git_index_conflict_get(git_index_entry **ancestor_out, git_index_entry **our_out, git_index_entry **their_out, git_index *index, const char *path);
 438
 439 /**
 440  * Removes the index entries that represent a conflict of a single file.
 441  *
 442  * @param index an existing index object
 443  * @param path to search
 444  */
 445 GIT_EXTERN(int) git_index_conflict_remove(git_index *index, const char *path);
 446
 447 /**
 448  * Remove all conflicts in the index (entries with a stage greater than 0.)
 449  *
 450  * @param index an existing index object
 451  */
 452 GIT_EXTERN(void) git_index_conflict_cleanup(git_index *index);
 453
 454 /**
 455  * Determine if the index contains entries representing file conflicts.
 456  *
 457  * @return 1 if at least one conflict is found, 0 otherwise.
 458  */
 459 GIT_EXTERN(int) git_index_has_conflicts(const git_index *index);
 460
 461 /**@}*/
 462
 463 /** @name Resolve Undo (REUC) index entry manipulation.
 464  *
 465  * These functions work on the Resolve Undo index extension and contains
 466  * data about the original files that led to a merge conflict.
 467  */
 468 /**@{*/
 469
 470 /**
 471  * Get the count of resolve undo entries currently in the index.
 472  *
 473  * @param index an existing index object
 474  * @return integer of count of current resolve undo entries
 475  */
 476 GIT_EXTERN(unsigned int) git_index_reuc_entrycount(git_index *index);
 477
 478 /**
 479  * Finds the resolve undo entry that points to the given path in the Git
 480  * index.
 481  *
 482  * @param index an existing index object
 483  * @param path path to search
 484  * @return an index >= 0 if found, -1 otherwise
 485  */
 486 GIT_EXTERN(int) git_index_reuc_find(git_index *index, const char *path);
 487
 488 /**
 489  * Get a resolve undo entry from the index.
 490  *
 491  * The returned entry is read-only and should not be modified
 492  * or freed by the caller.
 493  *
 494  * @param index an existing index object
 495  * @param path path to search
 496  * @return the resolve undo entry; NULL if not found
 497  */
 498 GIT_EXTERN(const git_index_reuc_entry *) git_index_reuc_get_bypath(git_index *index, const char *path);
 499
 500 /**
 501  * Get a resolve undo entry from the index.
 502  *
 503  * The returned entry is read-only and should not be modified
 504  * or freed by the caller.
 505  *
 506  * @param index an existing index object
 507  * @param n the position of the entry
 508  * @return a pointer to the resolve undo entry; NULL if out of bounds
 509  */
 510 GIT_EXTERN(const git_index_reuc_entry *) git_index_reuc_get_byindex(git_index *index, size_t n);
 511
 512 /**
 513  * Adds a resolve undo entry for a file based on the given parameters.
 514  *
 515  * The resolve undo entry contains the OIDs of files that were involved
 516  * in a merge conflict after the conflict has been resolved.  This allows
 517  * conflicts to be re-resolved later.
 518  *
 519  * If there exists a resolve undo entry for the given path in the index,
 520  * it will be removed.
 521  *
 522  * This method will fail in bare index instances.
 523  *
 524  * @param index an existing index object
 525  * @param path filename to add
 526  * @param ancestor_mode mode of the ancestor file
 527  * @param ancestor_id oid of the ancestor file
 528  * @param our_mode mode of our file
 529  * @param our_id oid of our file
 530  * @param their_mode mode of their file
 531  * @param their_id oid of their file
 532  * @return 0 or an error code
 533  */
 534 GIT_EXTERN(int) git_index_reuc_add(git_index *index, const char *path,
 535         int ancestor_mode, git_oid *ancestor_id,
 536         int our_mode, git_oid *our_id,
 537         int their_mode, git_oid *their_id);
 538
 539 /**
 540  * Remove an resolve undo entry from the index
 541  *
 542  * @param index an existing index object
 543  * @param n position of the resolve undo entry to remove
 544  * @return 0 or an error code
 545  */
 546 GIT_EXTERN(int) git_index_reuc_remove(git_index *index, size_t n);
 547
 548 /**@}*/
 549
 550 /** @} */
 551 GIT_END_DECL
 552 #endif