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 "types.h"
  12 #include "oid.h"
  13
  14 /**
  15  * @file git2/index.h
  16  * @brief Git index parsing and manipulation routines
  17  * @defgroup git_index Git index parsing and manipulation routines
  18  * @ingroup Git
  19  * @{
  20  */
  21 GIT_BEGIN_DECL
  22
  23 #define GIT_IDXENTRY_NAMEMASK (0x0fff)
  24 #define GIT_IDXENTRY_STAGEMASK (0x3000)
  25 #define GIT_IDXENTRY_EXTENDED (0x4000)
  26 #define GIT_IDXENTRY_VALID              (0x8000)
  27 #define GIT_IDXENTRY_STAGESHIFT 12
  28
  29 /*
  30  * Flags are divided into two parts: in-memory flags and
  31  * on-disk ones. Flags in GIT_IDXENTRY_EXTENDED_FLAGS
  32  * will get saved on-disk.
  33  *
  34  * In-memory only flags:
  35  */
  36 #define GIT_IDXENTRY_UPDATE                     (1 << 0)
  37 #define GIT_IDXENTRY_REMOVE                     (1 << 1)
  38 #define GIT_IDXENTRY_UPTODATE                   (1 << 2)
  39 #define GIT_IDXENTRY_ADDED                              (1 << 3)
  40
  41 #define GIT_IDXENTRY_HASHED                     (1 << 4)
  42 #define GIT_IDXENTRY_UNHASHED                   (1 << 5)
  43 #define GIT_IDXENTRY_WT_REMOVE                  (1 << 6) /* remove in work directory */
  44 #define GIT_IDXENTRY_CONFLICTED         (1 << 7)
  45
  46 #define GIT_IDXENTRY_UNPACKED                   (1 << 8)
  47 #define GIT_IDXENTRY_NEW_SKIP_WORKTREE (1 << 9)
  48
  49 /*
  50  * Extended on-disk flags:
  51  */
  52 #define GIT_IDXENTRY_INTENT_TO_ADD              (1 << 13)
  53 #define GIT_IDXENTRY_SKIP_WORKTREE              (1 << 14)
  54 /* GIT_IDXENTRY_EXTENDED2 is for future extension */
  55 #define GIT_IDXENTRY_EXTENDED2                  (1 << 15)
  56
  57 #define GIT_IDXENTRY_EXTENDED_FLAGS (GIT_IDXENTRY_INTENT_TO_ADD | GIT_IDXENTRY_SKIP_WORKTREE)
  58
  59 /** Time used in a git index entry */
  60 typedef struct {
  61         git_time_t seconds;
  62         /* nsec should not be stored as time_t compatible */
  63         unsigned int nanoseconds;
  64 } git_index_time;
  65
  66 /** Memory representation of a file entry in the index. */
  67 typedef struct git_index_entry {
  68         git_index_time ctime;
  69         git_index_time mtime;
  70
  71         unsigned int dev;
  72         unsigned int ino;
  73         unsigned int mode;
  74         unsigned int uid;
  75         unsigned int gid;
  76         git_off_t file_size;
  77
  78         git_oid oid;
  79
  80         unsigned short flags;
  81         unsigned short flags_extended;
  82
  83         char *path;
  84 } git_index_entry;
  85
  86 /** Representation of an unmerged file entry in the index. */
  87 typedef struct git_index_entry_unmerged {
  88         unsigned int mode[3];
  89         git_oid oid[3];
  90         char *path;
  91 } git_index_entry_unmerged;
  92
  93 /** Capabilities of system that affect index actions. */
  94 enum {
  95         GIT_INDEXCAP_IGNORE_CASE = 1,
  96         GIT_INDEXCAP_NO_FILEMODE = 2,
  97         GIT_INDEXCAP_NO_SYMLINKS = 4,
  98         GIT_INDEXCAP_FROM_OWNER  = ~0u
  99 };
 100
 101 /**
 102  * Create a new bare Git index object as a memory representation
 103  * of the Git index file in 'index_path', without a repository
 104  * to back it.
 105  *
 106  * Since there is no ODB or working directory behind this index,
 107  * any Index methods which rely on these (e.g. index_add) will
 108  * fail with the GIT_EBAREINDEX error code.
 109  *
 110  * If you need to access the index of an actual repository,
 111  * use the `git_repository_index` wrapper.
 112  *
 113  * The index must be freed once it's no longer in use.
 114  *
 115  * @param index the pointer for the new index
 116  * @param index_path the path to the index file in disk
 117  * @return 0 or an error code
 118  */
 119 GIT_EXTERN(int) git_index_open(git_index **index, const char *index_path);
 120
 121 /**
 122  * Clear the contents (all the entries) of an index object.
 123  * This clears the index object in memory; changes must be manually
 124  * written to disk for them to take effect.
 125  *
 126  * @param index an existing index object
 127  */
 128 GIT_EXTERN(void) git_index_clear(git_index *index);
 129
 130 /**
 131  * Free an existing index object.
 132  *
 133  * @param index an existing index object
 134  */
 135 GIT_EXTERN(void) git_index_free(git_index *index);
 136
 137 /**
 138  * Read index capabilities flags.
 139  *
 140  * @param index An existing index object
 141  * @return A combination of GIT_INDEXCAP values
 142  */
 143 GIT_EXTERN(unsigned int) git_index_caps(const git_index *index);
 144
 145 /**
 146  * Set index capabilities flags.
 147  *
 148  * If you pass `GIT_INDEXCAP_FROM_OWNER` for the caps, then the
 149  * capabilities will be read from the config of the owner object,
 150  * looking at `core.ignorecase`, `core.filemode`, `core.symlinks`.
 151  *
 152  * @param index An existing index object
 153  * @param caps A combination of GIT_INDEXCAP values
 154  * @return 0 on success, -1 on failure
 155  */
 156 GIT_EXTERN(int) git_index_set_caps(git_index *index, unsigned int caps);
 157
 158 /**
 159  * Update the contents of an existing index object in memory
 160  * by reading from the hard disk.
 161  *
 162  * @param index an existing index object
 163  * @return 0 or an error code
 164  */
 165 GIT_EXTERN(int) git_index_read(git_index *index);
 166
 167 /**
 168  * Write an existing index object from memory back to disk
 169  * using an atomic file lock.
 170  *
 171  * @param index an existing index object
 172  * @return 0 or an error code
 173  */
 174 GIT_EXTERN(int) git_index_write(git_index *index);
 175
 176 /**
 177  * Find the first index of any entries which point to given
 178  * path in the Git index.
 179  *
 180  * @param index an existing index object
 181  * @param path path to search
 182  * @return an index >= 0 if found, -1 otherwise
 183  */
 184 GIT_EXTERN(int) git_index_find(git_index *index, const char *path);
 185
 186 /**
 187  * Remove all entries with equal path except last added
 188  *
 189  * @param index an existing index object
 190  */
 191 GIT_EXTERN(void) git_index_uniq(git_index *index);
 192
 193 /**
 194  * Add or update an index entry from a file in disk
 195  *
 196  * The file `path` must be relative to the repository's
 197  * working folder and must be readable.
 198  *
 199  * This method will fail in bare index instances.
 200  *
 201  * This forces the file to be added to the index, not looking
 202  * at gitignore rules.  Those rules can be evaluated through
 203  * the git_status APIs (in status.h) before calling this.
 204  *
 205  * @param index an existing index object
 206  * @param path filename to add
 207  * @param stage stage for the entry
 208  * @return 0 or an error code
 209  */
 210 GIT_EXTERN(int) git_index_add(git_index *index, const char *path, int stage);
 211
 212 /**
 213  * Add or update an index entry from an in-memory struct
 214  *
 215  * A full copy (including the 'path' string) of the given
 216  * 'source_entry' will be inserted on the index.
 217  *
 218  * @param index an existing index object
 219  * @param source_entry new entry object
 220  * @return 0 or an error code
 221  */
 222 GIT_EXTERN(int) git_index_add2(git_index *index, const git_index_entry *source_entry);
 223
 224 /**
 225  * Add (append) an index entry from a file in disk
 226  *
 227  * A new entry will always be inserted into the index;
 228  * if the index already contains an entry for such
 229  * path, the old entry will **not** be replaced.
 230  *
 231  * The file `path` must be relative to the repository's
 232  * working folder and must be readable.
 233  *
 234  * This method will fail in bare index instances.
 235  *
 236  * @param index an existing index object
 237  * @param path filename to add
 238  * @param stage stage for the entry
 239  * @return 0 or an error code
 240  */
 241 GIT_EXTERN(int) git_index_append(git_index *index, const char *path, int stage);
 242
 243 /**
 244  * Add (append) an index entry from an in-memory struct
 245  *
 246  * A new entry will always be inserted into the index;
 247  * if the index already contains an entry for the path
 248  * in the `entry` struct, the old entry will **not** be
 249  * replaced.
 250  *
 251  * A full copy (including the 'path' string) of the given
 252  * 'source_entry' will be inserted on the index.
 253  *
 254  * @param index an existing index object
 255  * @param source_entry new entry object
 256  * @return 0 or an error code
 257  */
 258 GIT_EXTERN(int) git_index_append2(git_index *index, const git_index_entry *source_entry);
 259
 260 /**
 261  * Remove an entry from the index
 262  *
 263  * @param index an existing index object
 264  * @param position position of the entry to remove
 265  * @return 0 or an error code
 266  */
 267 GIT_EXTERN(int) git_index_remove(git_index *index, int position);
 268
 269
 270 /**
 271  * Get a pointer to one of the entries in the index
 272  *
 273  * This entry can be modified, and the changes will be written
 274  * back to disk on the next write() call.
 275  *
 276  * The entry should not be freed by the caller.
 277  *
 278  * @param index an existing index object
 279  * @param n the position of the entry
 280  * @return a pointer to the entry; NULL if out of bounds
 281  */
 282 GIT_EXTERN(git_index_entry *) git_index_get(git_index *index, size_t n);
 283
 284 /**
 285  * Get the count of entries currently in the index
 286  *
 287  * @param index an existing index object
 288  * @return integer of count of current entries
 289  */
 290 GIT_EXTERN(unsigned int) git_index_entrycount(git_index *index);
 291
 292 /**
 293  * Get the count of unmerged entries currently in the index
 294  *
 295  * @param index an existing index object
 296  * @return integer of count of current unmerged entries
 297  */
 298 GIT_EXTERN(unsigned int) git_index_entrycount_unmerged(git_index *index);
 299
 300 /**
 301  * Get an unmerged entry from the index.
 302  *
 303  * The returned entry is read-only and should not be modified
 304  * of freed by the caller.
 305  *
 306  * @param index an existing index object
 307  * @param path path to search
 308  * @return the unmerged entry; NULL if not found
 309  */
 310 GIT_EXTERN(const git_index_entry_unmerged *) git_index_get_unmerged_bypath(git_index *index, const char *path);
 311
 312 /**
 313  * Get an unmerged entry from the index.
 314  *
 315  * The returned entry is read-only and should not be modified
 316  * of freed by the caller.
 317  *
 318  * @param index an existing index object
 319  * @param n the position of the entry
 320  * @return a pointer to the unmerged entry; NULL if out of bounds
 321  */
 322 GIT_EXTERN(const git_index_entry_unmerged *) git_index_get_unmerged_byindex(git_index *index, size_t n);
 323
 324 /**
 325  * Return the stage number from a git index entry
 326  *
 327  * This entry is calculated from the entry's flag
 328  * attribute like this:
 329  *
 330  *      (entry->flags & GIT_IDXENTRY_STAGEMASK) >> GIT_IDXENTRY_STAGESHIFT
 331  *
 332  * @param entry The entry
 333  * @returns the stage number
 334  */
 335 GIT_EXTERN(int) git_index_entry_stage(const git_index_entry *entry);
 336
 337 /**
 338  * Read a tree into the index file
 339  *
 340  * The current index contents will be replaced by the specified tree.
 341  *
 342  * @param index an existing index object
 343  * @param tree tree to read
 344  * @return 0 or an error code
 345  */
 346 GIT_EXTERN(int) git_index_read_tree(git_index *index, git_tree *tree);
 347
 348 /** @} */
 349 GIT_END_DECL
 350 #endif