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 index 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 **index, const char *index_path);
 127
 128 /**
 129  * Free an existing index object.
 130  *
 131  * @param index an existing index object
 132  */
 133 GIT_EXTERN(void) git_index_free(git_index *index);
 134
 135 /**
 136  * Get the repository this index relates to
 137  *
 138  * @param index The index
 139  * @return A pointer to the repository
 140  */
 141 GIT_EXTERN(git_repository *) git_index_owner(const git_index *index);
 142
 143 /**
 144  * Read index capabilities flags.
 145  *
 146  * @param index An existing index object
 147  * @return A combination of GIT_INDEXCAP values
 148  */
 149 GIT_EXTERN(unsigned int) git_index_caps(const git_index *index);
 150
 151 /**
 152  * Set index capabilities flags.
 153  *
 154  * If you pass `GIT_INDEXCAP_FROM_OWNER` for the caps, then the
 155  * capabilities will be read from the config of the owner object,
 156  * looking at `core.ignorecase`, `core.filemode`, `core.symlinks`.
 157  *
 158  * @param index An existing index object
 159  * @param caps A combination of GIT_INDEXCAP values
 160  * @return 0 on success, -1 on failure
 161  */
 162 GIT_EXTERN(int) git_index_set_caps(git_index *index, unsigned int caps);
 163
 164 /**
 165  * Update the contents of an existing index object in memory
 166  * by reading from the hard disk.
 167  *
 168  * @param index an existing index object
 169  * @return 0 or an error code
 170  */
 171 GIT_EXTERN(int) git_index_read(git_index *index);
 172
 173 /**
 174  * Write an existing index object from memory back to disk
 175  * using an atomic file lock.
 176  *
 177  * @param index an existing index object
 178  * @return 0 or an error code
 179  */
 180 GIT_EXTERN(int) git_index_write(git_index *index);
 181
 182 /**
 183  * Read a tree into the index file with stats
 184  *
 185  * The current index contents will be replaced by the specified tree.
 186  *
 187  * @param index an existing index object
 188  * @param tree tree to read
 189  * @return 0 or an error code
 190  */
 191 GIT_EXTERN(int) git_index_read_tree(git_index *index, git_tree *tree);
 192
 193 /**
 194  * Write the index as a tree
 195  *
 196  * This method will scan the index and write a representation
 197  * of its current state back to disk; it recursively creates
 198  * tree objects for each of the subtrees stored in the index,
 199  * but only returns the OID of the root tree. This is the OID
 200  * that can be used e.g. to create a commit.
 201  *
 202  * The index instance cannot be bare, and needs to be associated
 203  * to an existing repository.
 204  *
 205  * @param oid Pointer where to store the OID of the written tree
 206  * @param index Index to write
 207  * @return 0 or an error code
 208  */
 209 GIT_EXTERN(int) git_index_write_tree(git_oid *oid, git_index *index);
 210
 211 /**
 212  * Write the index as a tree to the given repository
 213  *
 214  * This method will do the same as `git_index_write_tree`, but
 215  * letting the user choose the repository where the tree will
 216  * be written.
 217  *
 218  * @param oid Pointer where to store OID of the the written tree
 219  * @param index Index to write
 220  * @param repo Repository where to write the tree
 221  * @return 0 or an error code
 222  */
 223 GIT_EXTERN(int) git_index_write_tree_to(git_oid *oid, git_index *index, git_repository *repo);
 224
 225 /**@}*/
 226
 227 /** @name Raw Index Entry Functions
 228  *
 229  * These functions work on index entries, and allow for raw manipulation
 230  * of the entries.
 231  */
 232 /**@{*/
 233
 234 /* Index entry manipulation */
 235
 236 /**
 237  * Get the count of entries currently in the index
 238  *
 239  * @param index an existing index object
 240  * @return integer of count of current entries
 241  */
 242 GIT_EXTERN(unsigned int) git_index_entrycount(git_index *index);
 243
 244 /**
 245  * Clear the contents (all the entries) of an index object.
 246  * This clears the index object in memory; changes must be manually
 247  * written to disk for them to take effect.
 248  *
 249  * @param index an existing index object
 250  */
 251 GIT_EXTERN(void) git_index_clear(git_index *index);
 252
 253 /**
 254  * Get a pointer to one of the entries in the index
 255  *
 256  * The values of this entry can be modified (except the path)
 257  * and the changes will be written back to disk on the next
 258  * write() call.
 259  *
 260  * The entry should not be freed by the caller.
 261  *
 262  * @param index an existing index object
 263  * @param n the position of the entry
 264  * @return a pointer to the entry; NULL if out of bounds
 265  */
 266 GIT_EXTERN(git_index_entry *) git_index_get_byindex(git_index *index, size_t n);
 267
 268 /**
 269  * Get a pointer to one of the entries in the index
 270  *
 271  * The values of this entry can be modified (except the path)
 272  * and the changes will be written back to disk on the next
 273  * write() call.
 274  *
 275  * The entry should not be freed by the caller.
 276  *
 277  * @param index an existing index object
 278  * @param path path to search
 279  * @param stage stage to search
 280  * @return a pointer to the entry; NULL if it was not found
 281  */
 282 GIT_EXTERN(git_index_entry *) git_index_get_bypath(git_index *index, const char *path, int stage);
 283
 284 /**
 285  * Remove an entry from the index
 286  *
 287  * @param index an existing index object
 288  * @param path path to search
 289  * @param stage stage to search
 290  * @return 0 or an error code
 291  */
 292 GIT_EXTERN(int) git_index_remove(git_index *index, const char *path, int stage);
 293
 294 /**
 295  * Add or update an index entry from an in-memory struct
 296  *
 297  * If a previous index entry exists that has the same path and stage
 298  * as the given 'source_entry', it will be replaced.  Otherwise, the
 299  * 'source_entry' will be added.
 300  *
 301  * A full copy (including the 'path' string) of the given
 302  * 'source_entry' will be inserted on the index.
 303  *
 304  * @param index an existing index object
 305  * @param source_entry new entry object
 306  * @return 0 or an error code
 307  */
 308 GIT_EXTERN(int) git_index_add(git_index *index, const git_index_entry *source_entry);
 309
 310 /**
 311  * Return the stage number from a git index entry
 312  *
 313  * This entry is calculated from the entry's flag
 314  * attribute like this:
 315  *
 316  *      (entry->flags & GIT_IDXENTRY_STAGEMASK) >> GIT_IDXENTRY_STAGESHIFT
 317  *
 318  * @param entry The entry
 319  * @returns the stage number
 320  */
 321 GIT_EXTERN(int) git_index_entry_stage(const git_index_entry *entry);
 322
 323 /**@}*/
 324
 325 /** @name Workdir Index Entry Functions
 326  *
 327  * These functions work on index entries specifically in the working
 328  * directory (ie, stage 0).
 329  */
 330 /**@{*/
 331
 332 /**
 333  * Add or update an index entry from a file in disk
 334  *
 335  * The file `path` must be relative to the repository's
 336  * working folder and must be readable.
 337  *
 338  * This method will fail in bare index instances.
 339  *
 340  * This forces the file to be added to the index, not looking
 341  * at gitignore rules.  Those rules can be evaluated through
 342  * the git_status APIs (in status.h) before calling this.
 343  *
 344  * If this file currently is the result of a merge conflict, this
 345  * file will no longer be marked as conflicting.  The data about
 346  * the conflict will be moved to the "resolve undo" (REUC) section.
 347  *
 348  * @param index an existing index object
 349  * @param path filename to add
 350  * @return 0 or an error code
 351  */
 352 GIT_EXTERN(int) git_index_add_from_workdir(git_index *index, const char *path);
 353
 354 /**
 355  * Find the first index of any entries which point to given
 356  * path in the Git index.
 357  *
 358  * @param index an existing index object
 359  * @param path path to search
 360  * @return an index >= 0 if found, -1 otherwise
 361  */
 362 GIT_EXTERN(int) git_index_find(git_index *index, const char *path);
 363
 364 /**@}*/
 365
 366 /** @name Conflict Index Entry Functions
 367  *
 368  * These functions work on conflict index entries specifically (ie, stages 1-3)
 369  */
 370 /**@{*/
 371
 372 /**
 373  * Add or update index entries to represent a conflict
 374  *
 375  * The entries are the entries from the tree included in the merge.  Any
 376  * entry may be null to indicate that that file was not present in the
 377  * trees during the merge.  For example, ancestor_entry may be NULL to
 378  * indicate that a file was added in both branches and must be resolved.
 379  *
 380  * @param index an existing index object
 381  * @param ancestor_entry the entry data for the ancestor of the conflict
 382  * @param our_entry the entry data for our side of the merge conflict
 383  * @param their_entry the entry data for their side of the merge conflict
 384  * @return 0 or an error code
 385  */
 386 GIT_EXTERN(int) git_index_conflict_add(git_index *index,
 387         const git_index_entry *ancestor_entry,
 388         const git_index_entry *our_entry,
 389         const git_index_entry *their_entry);
 390
 391 /**
 392  * Get the index entries that represent a conflict of a single file.
 393  *
 394  * The values of this entry can be modified (except the paths)
 395  * and the changes will be written back to disk on the next
 396  * write() call.
 397  *
 398  * @param ancestor_out Pointer to store the ancestor entry
 399  * @param our_out Pointer to store the our entry
 400  * @param their_out Pointer to store the their entry
 401  * @param index an existing index object
 402  * @param path path to search
 403  */
 404 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);
 405
 406 /**
 407  * Removes the index entries that represent a conflict of a single file.
 408  *
 409  * @param index an existing index object
 410  * @param path to search
 411  */
 412 GIT_EXTERN(int) git_index_conflict_remove(git_index *index, const char *path);
 413
 414 /**
 415  * Remove all conflicts in the index (entries with a stage greater than 0.)
 416  *
 417  * @param index an existing index object
 418  */
 419 GIT_EXTERN(void) git_index_conflict_cleanup(git_index *index);
 420
 421 /**@}*/
 422
 423 /** @name Resolve Undo (REUC) index entry manipulation.
 424  *
 425  * These functions work on the Resolve Undo index extension and contains
 426  * data about the original files that led to a merge conflict.
 427  */
 428 /**@{*/
 429
 430 /**
 431  * Get the count of resolve undo entries currently in the index.
 432  *
 433  * @param index an existing index object
 434  * @return integer of count of current resolve undo entries
 435  */
 436 GIT_EXTERN(unsigned int) git_index_reuc_entrycount(git_index *index);
 437
 438 /**
 439  * Finds the resolve undo entry that points to the given path in the Git
 440  * index.
 441  *
 442  * @param index an existing index object
 443  * @param path path to search
 444  * @return an index >= 0 if found, -1 otherwise
 445  */
 446 GIT_EXTERN(int) git_index_reuc_find(git_index *index, const char *path);
 447
 448 /**
 449  * Get a resolve undo entry from the index.
 450  *
 451  * The returned entry is read-only and should not be modified
 452  * of freed by the caller.
 453  *
 454  * @param index an existing index object
 455  * @param path path to search
 456  * @return the resolve undo entry; NULL if not found
 457  */
 458 GIT_EXTERN(const git_index_reuc_entry *) git_index_reuc_get_bypath(git_index *index, const char *path);
 459
 460 /**
 461  * Get a resolve undo entry from the index.
 462  *
 463  * The returned entry is read-only and should not be modified
 464  * of freed by the caller.
 465  *
 466  * @param index an existing index object
 467  * @param n the position of the entry
 468  * @return a pointer to the resolve undo entry; NULL if out of bounds
 469  */
 470 GIT_EXTERN(const git_index_reuc_entry *) git_index_reuc_get_byindex(git_index *index, size_t n);
 471
 472 /**
 473  * Adds an resolve undo entry for a file based on the given parameters.
 474  *
 475  * The resolve undo entry contains the OIDs of files that were involved
 476  * in a merge conflict after the conflict has been resolved.  This allows
 477  * conflicts to be re-resolved later.
 478  *
 479  * If there exists a resolve undo entry for the given path in the index,
 480  * it will be removed.
 481  *
 482  * This method will fail in bare index instances.
 483  *
 484  * @param index an existing index object
 485  * @param path filename to add
 486  * @param ancestor_mode mode of the ancestor file
 487  * @param ancestor_oid oid of the ancestor file
 488  * @param our_mode mode of our file
 489  * @param our_oid oid of our file
 490  * @param their_mode mode of their file
 491  * @param their_oid oid of their file
 492  * @return 0 or an error code
 493  */
 494 GIT_EXTERN(int) git_index_reuc_add(git_index *index, const char *path,
 495         int ancestor_mode, git_oid *ancestor_oid,
 496         int our_mode, git_oid *our_oid,
 497         int their_mode, git_oid *their_oid);
 498
 499 /**
 500  * Remove an resolve undo entry from the index
 501  *
 502  * @param index an existing index object
 503  * @param position position of the resolve undo entry to remove
 504  * @return 0 or an error code
 505  */
 506 GIT_EXTERN(int) git_index_reuc_remove(git_index *index, int position);
 507
 508 /**@}*/
 509
 510 /** @} */
 511 GIT_END_DECL
 512 #endif