date: make DATE_MODE thread-safe
[git.git] / tree-walk.h
bloba6bfa3da3a826bf5c218132b93582e53ace876be
1 #ifndef TREE_WALK_H
2 #define TREE_WALK_H
4 #include "hash-ll.h"
6 struct index_state;
7 struct repository;
9 /**
10 * The tree walking API is used to traverse and inspect trees.
13 /**
14 * An entry in a tree. Each entry has a sha1 identifier, pathname, and mode.
16 struct name_entry {
17 struct object_id oid;
18 const char *path;
19 int pathlen;
20 unsigned int mode;
23 /**
24 * A semi-opaque data structure used to maintain the current state of the walk.
26 struct tree_desc {
28 * pointer into the memory representation of the tree. It always
29 * points at the current entry being visited.
31 const void *buffer;
33 /* points to the current entry being visited. */
34 struct name_entry entry;
36 /* counts the number of bytes left in the `buffer`. */
37 unsigned int size;
39 /* option flags passed via init_tree_desc_gently() */
40 enum tree_desc_flags {
41 TREE_DESC_RAW_MODES = (1 << 0),
42 } flags;
45 /**
46 * Decode the entry currently being visited (the one pointed to by
47 * `tree_desc's` `entry` member) and return the sha1 of the entry. The
48 * `pathp` and `modep` arguments are set to the entry's pathname and mode
49 * respectively.
51 static inline const struct object_id *tree_entry_extract(struct tree_desc *desc, const char **pathp, unsigned short *modep)
53 *pathp = desc->entry.path;
54 *modep = desc->entry.mode;
55 return &desc->entry.oid;
58 /**
59 * Calculate the length of a tree entry's pathname. This utilizes the
60 * memory structure of a tree entry to avoid the overhead of using a
61 * generic strlen().
63 static inline int tree_entry_len(const struct name_entry *ne)
65 return ne->pathlen;
69 * The _gently versions of these functions warn and return false on a
70 * corrupt tree entry rather than dying,
73 /**
74 * Walk to the next entry in a tree. This is commonly used in conjunction
75 * with `tree_entry_extract` to inspect the current entry.
77 void update_tree_entry(struct tree_desc *);
79 int update_tree_entry_gently(struct tree_desc *);
81 /**
82 * Initialize a `tree_desc` and decode its first entry. The buffer and
83 * size parameters are assumed to be the same as the buffer and size
84 * members of `struct tree`.
86 void init_tree_desc(struct tree_desc *desc, const void *buf, unsigned long size);
88 int init_tree_desc_gently(struct tree_desc *desc, const void *buf, unsigned long size,
89 enum tree_desc_flags flags);
92 * Visit the next entry in a tree. Returns 1 when there are more entries
93 * left to visit and 0 when all entries have been visited. This is
94 * commonly used in the test of a while loop.
96 int tree_entry(struct tree_desc *, struct name_entry *);
98 int tree_entry_gently(struct tree_desc *, struct name_entry *);
101 * Initialize a `tree_desc` and decode its first entry given the
102 * object ID of a tree. Returns the `buffer` member if the latter
103 * is a valid tree identifier and NULL otherwise.
105 void *fill_tree_descriptor(struct repository *r,
106 struct tree_desc *desc,
107 const struct object_id *oid);
109 struct traverse_info;
110 typedef int (*traverse_callback_t)(int n, unsigned long mask, unsigned long dirmask, struct name_entry *entry, struct traverse_info *);
113 * Traverse `n` number of trees in parallel. The `fn` callback member of
114 * `traverse_info` is called once for each tree entry.
116 int traverse_trees(struct index_state *istate, int n, struct tree_desc *t, struct traverse_info *info);
118 enum get_oid_result get_tree_entry_follow_symlinks(struct repository *r, struct object_id *tree_oid, const char *name, struct object_id *result, struct strbuf *result_path, unsigned short *mode);
121 * A structure used to maintain the state of a traversal.
123 struct traverse_info {
124 const char *traverse_path;
127 * points to the traverse_info which was used to descend into the
128 * current tree. If this is the top-level tree `prev` will point to
129 * a dummy traverse_info.
131 struct traverse_info *prev;
133 /* is the entry for the current tree (if the tree is a subtree). */
134 const char *name;
136 size_t namelen;
137 unsigned mode;
139 /* is the length of the full path for the current tree. */
140 size_t pathlen;
142 struct pathspec *pathspec;
144 /* can be used by callbacks to maintain directory-file conflicts. */
145 unsigned long df_conflicts;
147 /* a callback called for each entry in the tree.
149 * The arguments passed to the traverse callback are as follows:
151 * - `n` counts the number of trees being traversed.
153 * - `mask` has its nth bit set if something exists in the nth entry.
155 * - `dirmask` has its nth bit set if the nth tree's entry is a directory.
157 * - `entry` is an array of size `n` where the nth entry is from the nth tree.
159 * - `info` maintains the state of the traversal.
161 * Returning a negative value will terminate the traversal. Otherwise the
162 * return value is treated as an update mask. If the nth bit is set the nth tree
163 * will be updated and if the bit is not set the nth tree entry will be the
164 * same in the next callback invocation.
166 traverse_callback_t fn;
168 /* can be anything the `fn` callback would want to use. */
169 void *data;
171 /* tells whether to stop at the first error or not. */
172 int show_all_errors;
176 * Find an entry in a tree given a pathname and the sha1 of a tree to
177 * search. Returns 0 if the entry is found and -1 otherwise. The third
178 * and fourth parameters are set to the entry's sha1 and mode respectively.
180 int get_tree_entry(struct repository *, const struct object_id *, const char *, struct object_id *, unsigned short *);
183 * Generate the full pathname of a tree entry based from the root of the
184 * traversal. For example, if the traversal has recursed into another
185 * tree named "bar" the pathname of an entry "baz" in the "bar"
186 * tree would be "bar/baz".
188 char *make_traverse_path(char *path, size_t pathlen, const struct traverse_info *info,
189 const char *name, size_t namelen);
192 * Convenience wrapper to `make_traverse_path` into a strbuf.
194 void strbuf_make_traverse_path(struct strbuf *out,
195 const struct traverse_info *info,
196 const char *name, size_t namelen);
199 * Initialize a `traverse_info` given the pathname of the tree to start
200 * traversing from.
202 void setup_traverse_info(struct traverse_info *info, const char *base);
205 * Calculate the length of a pathname returned by `make_traverse_path`.
206 * This utilizes the memory structure of a tree entry to avoid the
207 * overhead of using a generic strlen().
209 static inline size_t traverse_path_len(const struct traverse_info *info,
210 size_t namelen)
212 return st_add(info->pathlen, namelen);
215 /* in general, positive means "kind of interesting" */
216 enum interesting {
217 all_entries_not_interesting = -1, /* no, and no subsequent entries will be either */
218 entry_not_interesting = 0,
219 entry_interesting = 1,
220 all_entries_interesting = 2 /* yes, and all subsequent entries will be */
223 enum interesting tree_entry_interesting(struct index_state *istate,
224 const struct name_entry *,
225 struct strbuf *,
226 const struct pathspec *ps);
228 #endif