"Fossies" - the Fresh Open Source Software Archive

Member "git-2.23.0.windows.1/Documentation/technical/api-ref-iteration.txt" (16 Aug 2019, 2311 Bytes) of package /windows/misc/git-2.23.0.windows.1.zip:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "api-ref-iteration.txt": 2.23.0-rc1_vs_2.23.0-rc2.

    1 ref iteration API
    2 =================
    3 
    4 
    5 Iteration of refs is done by using an iterate function which will call a
    6 callback function for every ref. The callback function has this
    7 signature:
    8 
    9 	int handle_one_ref(const char *refname, const struct object_id *oid,
   10 			   int flags, void *cb_data);
   11 
   12 There are different kinds of iterate functions which all take a
   13 callback of this type. The callback is then called for each found ref
   14 until the callback returns nonzero. The returned value is then also
   15 returned by the iterate function.
   16 
   17 Iteration functions
   18 -------------------
   19 
   20 * `head_ref()` just iterates the head ref.
   21 
   22 * `for_each_ref()` iterates all refs.
   23 
   24 * `for_each_ref_in()` iterates all refs which have a defined prefix and
   25   strips that prefix from the passed variable refname.
   26 
   27 * `for_each_tag_ref()`, `for_each_branch_ref()`, `for_each_remote_ref()`,
   28   `for_each_replace_ref()` iterate refs from the respective area.
   29 
   30 * `for_each_glob_ref()` iterates all refs that match the specified glob
   31   pattern.
   32 
   33 * `for_each_glob_ref_in()` the previous and `for_each_ref_in()` combined.
   34 
   35 * Use `refs_` API for accessing submodules. The submodule ref store could
   36   be obtained with `get_submodule_ref_store()`.
   37 
   38 * `for_each_rawref()` can be used to learn about broken ref and symref.
   39 
   40 * `for_each_reflog()` iterates each reflog file.
   41 
   42 Submodules
   43 ----------
   44 
   45 If you want to iterate the refs of a submodule you first need to add the
   46 submodules object database. You can do this by a code-snippet like
   47 this:
   48 
   49 	const char *path = "path/to/submodule"
   50 	if (add_submodule_odb(path))
   51 		die("Error submodule '%s' not populated.", path);
   52 
   53 `add_submodule_odb()` will return zero on success. If you
   54 do not do this you will get an error for each ref that it does not point
   55 to a valid object.
   56 
   57 Note: As a side-effect of this you cannot safely assume that all
   58 objects you lookup are available in superproject. All submodule objects
   59 will be available the same way as the superprojects objects.
   60 
   61 Example:
   62 --------
   63 
   64 ----
   65 static int handle_remote_ref(const char *refname,
   66 		const unsigned char *sha1, int flags, void *cb_data)
   67 {
   68 	struct strbuf *output = cb_data;
   69 	strbuf_addf(output, "%s\n", refname);
   70 	return 0;
   71 }
   72 
   73 ...
   74 
   75 	struct strbuf output = STRBUF_INIT;
   76 	for_each_remote_ref(handle_remote_ref, &output);
   77 	printf("%s", output.buf);
   78 ----