]>
Commit | Line | Data |
---|---|---|
1 | #ifndef TREE_WALK_H | |
2 | #define TREE_WALK_H | |
3 | ||
4 | #include "cache.h" | |
5 | ||
6 | /** | |
7 | * The tree walking API is used to traverse and inspect trees. | |
8 | */ | |
9 | ||
10 | /** | |
11 | * An entry in a tree. Each entry has a sha1 identifier, pathname, and mode. | |
12 | */ | |
13 | struct name_entry { | |
14 | struct object_id oid; | |
15 | const char *path; | |
16 | int pathlen; | |
17 | unsigned int mode; | |
18 | }; | |
19 | ||
20 | /** | |
21 | * A semi-opaque data structure used to maintain the current state of the walk. | |
22 | */ | |
23 | struct tree_desc { | |
24 | /* | |
25 | * pointer into the memory representation of the tree. It always | |
26 | * points at the current entry being visited. | |
27 | */ | |
28 | const void *buffer; | |
29 | ||
30 | /* points to the current entry being visited. */ | |
31 | struct name_entry entry; | |
32 | ||
33 | /* counts the number of bytes left in the `buffer`. */ | |
34 | unsigned int size; | |
35 | }; | |
36 | ||
37 | /** | |
38 | * Decode the entry currently being visited (the one pointed to by | |
39 | * `tree_desc's` `entry` member) and return the sha1 of the entry. The | |
40 | * `pathp` and `modep` arguments are set to the entry's pathname and mode | |
41 | * respectively. | |
42 | */ | |
43 | static inline const struct object_id *tree_entry_extract(struct tree_desc *desc, const char **pathp, unsigned short *modep) | |
44 | { | |
45 | *pathp = desc->entry.path; | |
46 | *modep = desc->entry.mode; | |
47 | return &desc->entry.oid; | |
48 | } | |
49 | ||
50 | /** | |
51 | * Calculate the length of a tree entry's pathname. This utilizes the | |
52 | * memory structure of a tree entry to avoid the overhead of using a | |
53 | * generic strlen(). | |
54 | */ | |
55 | static inline int tree_entry_len(const struct name_entry *ne) | |
56 | { | |
57 | return ne->pathlen; | |
58 | } | |
59 | ||
60 | /* | |
61 | * The _gently versions of these functions warn and return false on a | |
62 | * corrupt tree entry rather than dying, | |
63 | */ | |
64 | ||
65 | /** | |
66 | * Walk to the next entry in a tree. This is commonly used in conjunction | |
67 | * with `tree_entry_extract` to inspect the current entry. | |
68 | */ | |
69 | void update_tree_entry(struct tree_desc *); | |
70 | ||
71 | int update_tree_entry_gently(struct tree_desc *); | |
72 | ||
73 | /** | |
74 | * Initialize a `tree_desc` and decode its first entry. The buffer and | |
75 | * size parameters are assumed to be the same as the buffer and size | |
76 | * members of `struct tree`. | |
77 | */ | |
78 | void init_tree_desc(struct tree_desc *desc, const void *buf, unsigned long size); | |
79 | ||
80 | int init_tree_desc_gently(struct tree_desc *desc, const void *buf, unsigned long size); | |
81 | ||
82 | /* | |
83 | * Visit the next entry in a tree. Returns 1 when there are more entries | |
84 | * left to visit and 0 when all entries have been visited. This is | |
85 | * commonly used in the test of a while loop. | |
86 | */ | |
87 | int tree_entry(struct tree_desc *, struct name_entry *); | |
88 | ||
89 | int tree_entry_gently(struct tree_desc *, struct name_entry *); | |
90 | ||
91 | /** | |
92 | * Initialize a `tree_desc` and decode its first entry given the | |
93 | * object ID of a tree. Returns the `buffer` member if the latter | |
94 | * is a valid tree identifier and NULL otherwise. | |
95 | */ | |
96 | void *fill_tree_descriptor(struct repository *r, | |
97 | struct tree_desc *desc, | |
98 | const struct object_id *oid); | |
99 | ||
100 | struct traverse_info; | |
101 | typedef int (*traverse_callback_t)(int n, unsigned long mask, unsigned long dirmask, struct name_entry *entry, struct traverse_info *); | |
102 | ||
103 | /** | |
104 | * Traverse `n` number of trees in parallel. The `fn` callback member of | |
105 | * `traverse_info` is called once for each tree entry. | |
106 | */ | |
107 | int traverse_trees(struct index_state *istate, int n, struct tree_desc *t, struct traverse_info *info); | |
108 | ||
109 | 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); | |
110 | ||
111 | /** | |
112 | * A structure used to maintain the state of a traversal. | |
113 | */ | |
114 | struct traverse_info { | |
115 | const char *traverse_path; | |
116 | ||
117 | /* | |
118 | * points to the traverse_info which was used to descend into the | |
119 | * current tree. If this is the top-level tree `prev` will point to | |
120 | * a dummy traverse_info. | |
121 | */ | |
122 | struct traverse_info *prev; | |
123 | ||
124 | /* is the entry for the current tree (if the tree is a subtree). */ | |
125 | const char *name; | |
126 | ||
127 | size_t namelen; | |
128 | unsigned mode; | |
129 | ||
130 | /* is the length of the full path for the current tree. */ | |
131 | size_t pathlen; | |
132 | ||
133 | struct pathspec *pathspec; | |
134 | ||
135 | /* can be used by callbacks to maintain directory-file conflicts. */ | |
136 | unsigned long df_conflicts; | |
137 | ||
138 | /* a callback called for each entry in the tree. | |
139 | * | |
140 | * The arguments passed to the traverse callback are as follows: | |
141 | * | |
142 | * - `n` counts the number of trees being traversed. | |
143 | * | |
144 | * - `mask` has its nth bit set if something exists in the nth entry. | |
145 | * | |
146 | * - `dirmask` has its nth bit set if the nth tree's entry is a directory. | |
147 | * | |
148 | * - `entry` is an array of size `n` where the nth entry is from the nth tree. | |
149 | * | |
150 | * - `info` maintains the state of the traversal. | |
151 | * | |
152 | * Returning a negative value will terminate the traversal. Otherwise the | |
153 | * return value is treated as an update mask. If the nth bit is set the nth tree | |
154 | * will be updated and if the bit is not set the nth tree entry will be the | |
155 | * same in the next callback invocation. | |
156 | */ | |
157 | traverse_callback_t fn; | |
158 | ||
159 | /* can be anything the `fn` callback would want to use. */ | |
160 | void *data; | |
161 | ||
162 | /* tells whether to stop at the first error or not. */ | |
163 | int show_all_errors; | |
164 | }; | |
165 | ||
166 | /** | |
167 | * Find an entry in a tree given a pathname and the sha1 of a tree to | |
168 | * search. Returns 0 if the entry is found and -1 otherwise. The third | |
169 | * and fourth parameters are set to the entry's sha1 and mode respectively. | |
170 | */ | |
171 | int get_tree_entry(struct repository *, const struct object_id *, const char *, struct object_id *, unsigned short *); | |
172 | ||
173 | /** | |
174 | * Generate the full pathname of a tree entry based from the root of the | |
175 | * traversal. For example, if the traversal has recursed into another | |
176 | * tree named "bar" the pathname of an entry "baz" in the "bar" | |
177 | * tree would be "bar/baz". | |
178 | */ | |
179 | char *make_traverse_path(char *path, size_t pathlen, const struct traverse_info *info, | |
180 | const char *name, size_t namelen); | |
181 | ||
182 | /** | |
183 | * Convenience wrapper to `make_traverse_path` into a strbuf. | |
184 | */ | |
185 | void strbuf_make_traverse_path(struct strbuf *out, | |
186 | const struct traverse_info *info, | |
187 | const char *name, size_t namelen); | |
188 | ||
189 | /** | |
190 | * Initialize a `traverse_info` given the pathname of the tree to start | |
191 | * traversing from. | |
192 | */ | |
193 | void setup_traverse_info(struct traverse_info *info, const char *base); | |
194 | ||
195 | /** | |
196 | * Calculate the length of a pathname returned by `make_traverse_path`. | |
197 | * This utilizes the memory structure of a tree entry to avoid the | |
198 | * overhead of using a generic strlen(). | |
199 | */ | |
200 | static inline size_t traverse_path_len(const struct traverse_info *info, | |
201 | size_t namelen) | |
202 | { | |
203 | return st_add(info->pathlen, namelen); | |
204 | } | |
205 | ||
206 | /* in general, positive means "kind of interesting" */ | |
207 | enum interesting { | |
208 | all_entries_not_interesting = -1, /* no, and no subsequent entries will be either */ | |
209 | entry_not_interesting = 0, | |
210 | entry_interesting = 1, | |
211 | all_entries_interesting = 2 /* yes, and all subsequent entries will be */ | |
212 | }; | |
213 | ||
214 | enum interesting tree_entry_interesting(struct index_state *istate, | |
215 | const struct name_entry *, | |
216 | struct strbuf *, int, | |
217 | const struct pathspec *ps); | |
218 | ||
219 | #endif |