Merge branch 'sb/in-core-index-doc'
authorJunio C Hamano <gitster@pobox.com>
Tue, 31 Jan 2017 21:14:59 +0000 (13:14 -0800)
committerJunio C Hamano <gitster@pobox.com>
Tue, 31 Jan 2017 21:14:59 +0000 (13:14 -0800)
Documentation and in-code comments updates.

* sb/in-core-index-doc:
documentation: retire unfinished documentation
cache.h: document add_[file_]to_index
cache.h: document remove_index_entry_at
cache.h: document index_name_pos

1  2 
cache.h
read-cache.c
diff --combined cache.h
index 5cac28788df7a28e812404970e036ad014edcdb6,b36b4fa31b3f123daf59d56064b59bef713ed9af..674ae7e662a5dc79054d8f5b3eb3e83da198dcf6
+++ b/cache.h
@@@ -514,6 -514,7 +514,6 @@@ extern void set_git_work_tree(const cha
  
  #define ALTERNATE_DB_ENVIRONMENT "GIT_ALTERNATE_OBJECT_DIRECTORIES"
  
 -extern const char **get_pathspec(const char *prefix, const char **pathspec);
  extern void setup_work_tree(void);
  extern const char *setup_git_directory_gently(int *);
  extern const char *setup_git_directory(void);
@@@ -574,7 -575,26 +574,26 @@@ extern int verify_path(const char *path
  extern int index_dir_exists(struct index_state *istate, const char *name, int namelen);
  extern void adjust_dirname_case(struct index_state *istate, char *name);
  extern struct cache_entry *index_file_exists(struct index_state *istate, const char *name, int namelen, int igncase);
+ /*
+  * Searches for an entry defined by name and namelen in the given index.
+  * If the return value is positive (including 0) it is the position of an
+  * exact match. If the return value is negative, the negated value minus 1
+  * is the position where the entry would be inserted.
+  * Example: The current index consists of these files and its stages:
+  *
+  *   b#0, d#0, f#1, f#3
+  *
+  * index_name_pos(&index, "a", 1) -> -1
+  * index_name_pos(&index, "b", 1) ->  0
+  * index_name_pos(&index, "c", 1) -> -2
+  * index_name_pos(&index, "d", 1) ->  1
+  * index_name_pos(&index, "e", 1) -> -3
+  * index_name_pos(&index, "f", 1) -> -3
+  * index_name_pos(&index, "g", 1) -> -5
+  */
  extern int index_name_pos(const struct index_state *, const char *name, int namelen);
  #define ADD_CACHE_OK_TO_ADD 1         /* Ok to add */
  #define ADD_CACHE_OK_TO_REPLACE 2     /* Ok to replace file/directory */
  #define ADD_CACHE_SKIP_DFCHECK 4      /* Ok to skip DF conflict checks */
  #define ADD_CACHE_KEEP_CACHE_TREE 32  /* Do not invalidate cache-tree */
  extern int add_index_entry(struct index_state *, struct cache_entry *ce, int option);
  extern void rename_index_entry_at(struct index_state *, int pos, const char *new_name);
+ /* Remove entry, return true if there are more entries to go. */
  extern int remove_index_entry_at(struct index_state *, int pos);
  extern void remove_marked_cache_entries(struct index_state *istate);
  extern int remove_file_from_index(struct index_state *, const char *path);
  #define ADD_CACHE_VERBOSE 1
  #define ADD_CACHE_IGNORE_ERRORS       4
  #define ADD_CACHE_IGNORE_REMOVAL 8
  #define ADD_CACHE_INTENT 16
+ /*
+  * These two are used to add the contents of the file at path
+  * to the index, marking the working tree up-to-date by storing
+  * the cached stat info in the resulting cache entry.  A caller
+  * that has already run lstat(2) on the path can call
+  * add_to_index(), and all others can call add_file_to_index();
+  * the latter will do necessary lstat(2) internally before
+  * calling the former.
+  */
  extern int add_to_index(struct index_state *, const char *path, struct stat *, int flags);
  extern int add_file_to_index(struct index_state *, const char *path, int flags);
  extern struct cache_entry *make_cache_entry(unsigned int mode, const unsigned char *sha1, const char *path, int stage, unsigned int refresh_options);
  extern int chmod_index_entry(struct index_state *, struct cache_entry *ce, char flip);
  extern int ce_same_name(const struct cache_entry *a, const struct cache_entry *b);
  extern void set_object_name_for_intent_to_add_entry(struct cache_entry *ce);
  extern int index_name_is_other(const struct index_state *, const char *, int);
 -extern void *read_blob_data_from_index(struct index_state *, const char *, unsigned long *);
 +extern void *read_blob_data_from_index(const struct index_state *, const char *, unsigned long *);
  
  /* do stat comparison even if CE_VALID is true */
  #define CE_MATCH_IGNORE_VALID         01
@@@ -669,7 -702,7 +701,7 @@@ extern const char *git_attributes_file
  extern const char *git_hooks_path;
  extern int zlib_compression_level;
  extern int core_compression_level;
 -extern int core_compression_seen;
 +extern int pack_compression_level;
  extern size_t packed_git_window_size;
  extern size_t packed_git_limit;
  extern size_t delta_base_cache_limit;
@@@ -1063,11 -1096,8 +1095,11 @@@ static inline int is_absolute_path(cons
        return is_dir_sep(path[0]) || has_dos_drive_prefix(path);
  }
  int is_directory(const char *);
 +char *strbuf_realpath(struct strbuf *resolved, const char *path,
 +                    int die_on_error);
  const char *real_path(const char *path);
  const char *real_path_if_valid(const char *path);
 +char *real_pathdup(const char *path);
  const char *absolute_path(const char *path);
  const char *remove_leading_path(const char *in, const char *prefix);
  const char *relative_path(const char *in, const char *prefix, struct strbuf *sb);
@@@ -1127,8 -1157,7 +1159,8 @@@ extern int write_sha1_file(const void *
  extern int hash_sha1_file_literally(const void *buf, unsigned long len, const char *type, unsigned char *sha1, unsigned flags);
  extern int pretend_sha1_file(void *, unsigned long, enum object_type, unsigned char *);
  extern int force_object_loose(const unsigned char *sha1, time_t mtime);
 -extern int git_open(const char *name);
 +extern int git_open_cloexec(const char *name, int flags);
 +#define git_open(name) git_open_cloexec(name, O_RDONLY)
  extern void *map_sha1_file(const unsigned char *sha1, unsigned long *size);
  extern int unpack_sha1_header(git_zstream *stream, unsigned char *map, unsigned long mapsize, void *buffer, unsigned long bufsiz);
  extern int parse_sha1_header(const char *hdr, unsigned long *sizep);
@@@ -1142,19 -1171,6 +1174,19 @@@ extern int finalize_object_file(const c
  
  extern int has_sha1_pack(const unsigned char *sha1);
  
 +/*
 + * Open the loose object at path, check its sha1, and return the contents,
 + * type, and size. If the object is a blob, then "contents" may return NULL,
 + * to allow streaming of large blobs.
 + *
 + * Returns 0 on success, negative on error (details may be written to stderr).
 + */
 +int read_loose_object(const char *path,
 +                    const unsigned char *expected_sha1,
 +                    enum object_type *type,
 +                    unsigned long *size,
 +                    void **contents);
 +
  /*
   * Return true iff we have an object named sha1, whether local or in
   * an alternate object database, and whether packed or loose.  This
@@@ -1706,8 -1722,6 +1738,8 @@@ extern int git_default_config(const cha
  extern int git_config_from_file(config_fn_t fn, const char *, void *);
  extern int git_config_from_mem(config_fn_t fn, const enum config_origin_type,
                                        const char *name, const char *buf, size_t len, void *data);
 +extern int git_config_from_blob_sha1(config_fn_t fn, const char *name,
 +                                   const unsigned char *sha1, void *data);
  extern void git_config_push_parameter(const char *text);
  extern int git_config_from_parameters(config_fn_t fn, void *data);
  extern void git_config(config_fn_t fn, void *);
diff --combined read-cache.c
index 7a9a7de91e6e84c429b0d485301c3500e404dd2f,585ff02dc3307daf1959867183b1beed0917fb0b..9054369dd0c6ddfd35794fc63f0e0296ec0c9c91
@@@ -156,7 -156,14 +156,7 @@@ void fill_stat_cache_info(struct cache_
  static int ce_compare_data(const struct cache_entry *ce, struct stat *st)
  {
        int match = -1;
 -      static int cloexec = O_CLOEXEC;
 -      int fd = open(ce->name, O_RDONLY | cloexec);
 -
 -      if ((cloexec & O_CLOEXEC) && fd < 0 && errno == EINVAL) {
 -              /* Try again w/o O_CLOEXEC: the kernel might not support it */
 -              cloexec &= ~O_CLOEXEC;
 -              fd = open(ce->name, O_RDONLY | cloexec);
 -      }
 +      int fd = git_open_cloexec(ce->name, O_RDONLY);
  
        if (fd >= 0) {
                unsigned char sha1[20];
@@@ -503,7 -510,6 +503,6 @@@ int index_name_pos(const struct index_s
        return index_name_stage_pos(istate, name, namelen, 0);
  }
  
- /* Remove entry, return true if there are more entries to go.. */
  int remove_index_entry_at(struct index_state *istate, int pos)
  {
        struct cache_entry *ce = istate->cache[pos];
@@@ -1418,9 -1424,12 +1417,9 @@@ static int read_index_extension(struct 
        return 0;
  }
  
 -int hold_locked_index(struct lock_file *lk, int die_on_error)
 +int hold_locked_index(struct lock_file *lk, int lock_flags)
  {
 -      return hold_lock_file_for_update(lk, get_index_file(),
 -                                       die_on_error
 -                                       ? LOCK_DIE_ON_ERROR
 -                                       : 0);
 +      return hold_lock_file_for_update(lk, get_index_file(), lock_flags);
  }
  
  int read_index(struct index_state *istate)
@@@ -2285,8 -2294,7 +2284,8 @@@ int index_name_is_other(const struct in
        return 1;
  }
  
 -void *read_blob_data_from_index(struct index_state *istate, const char *path, unsigned long *size)
 +void *read_blob_data_from_index(const struct index_state *istate,
 +                              const char *path, unsigned long *size)
  {
        int pos, len;
        unsigned long sz;