[PATCH] add technical documentation about ref iteration

[PATCH] add technical documentation about ref iteration

[Heiko Voigt]

Signed-off-by: Heiko Voigt <hvoigt@hvoigt.net>
---
 Documentation/technical/api-ref-iteration.txt |   73 +++++++++++++++++++++++++
 1 files changed, 73 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/technical/api-ref-iteration.txt

diff --git a/Documentation/technical/api-ref-iteration.txt b/Documentation/technical/api-ref-iteration.txt
new file mode 100644
index 0000000..0a67e39
--- /dev/null
+++ b/Documentation/technical/api-ref-iteration.txt
@@ -0,0 +1,73 @@
+ref iteration API
+=================
+
+
+Iteration of refs is done by using an iterate function which will call a
+callback function for every ref. The callback function has this
+signature:
+
+	int handle_one_ref(const char *refname, const unsigned char *sha1,
+			   int flags, void *cb_data);
+
+There are different kinds of iterate functions which all take a
+callback of this type. The callback is then called for each found ref
+until the callback returns nonzero. The returned value is then also
+returned by the iterate function.
+
+Iteration functions
+-------------------
+
+* `head_ref()` just iterates the head ref.
+
+* `for_each_ref()` iterates all refs.
+
+* `for_each_ref_in()` iterates all refs which have a defined prefix and
+  strips that prefix from the passed variable refname.
+
+* `for_each_tag_ref()`, `for_each_branch_ref()`, `for_each_remote_ref()`,
+  `for_each_replace_ref()` iterate refs from the respective area.
+
+* `for_each_glob_ref()` iterates all refs that match the specified glob
+  pattern.
+
+* `for_each_glob_ref_in()` the previous and `for_each_ref_in()` combined.
+
+* `head_ref_submodule()`, `for_each_ref_submodule()`,
+  `for_each_ref_in_submodule()`, `for_each_tag_ref_submodule()`,
+  `for_each_branch_ref_submodule()`, `for_each_remote_ref_submodule()`
+  do the same as the functions descibed above but for a specified
+  submodule.
+
+* `for_each_rawref()` can be used to learn about broken ref and symref.
+
+* `for_each_reflog()` iterates each reflog file.
+
+Submodules
+----------
+
+If you want to iterate the refs of a submodule you first need to call
+
+	add_submodule_odb(submodule)
+
+and test whether that succeeds.
+
+Example:
+--------
+
+----
+static int handle_remote_ref(const char *refname,
+		const unsigned char *sha1, int flags, void *cb_data)
+{
+	struct strbuf *output = cb_data;
+	strbuf_addf(output, "%s\n", refname);
+	return 0;
+}
+
+...
+
+	struct strbuf output = STRBUF_INIT;
+	for_each_remote_ref(handle_remote_ref, &output);
+	printf("%s", output.buf);
+----
+
+(Heiko Voigt)
-- 
1.7.6.353.g02057.dirty

Re: [PATCH] add technical documentation about ref iteration

[Junio C Hamano]

Heiko Voigt <hvoigt@hvoigt.net> writes:

> Signed-off-by: Heiko Voigt <hvoigt@hvoigt.net>
> ---
>  Documentation/technical/api-ref-iteration.txt |   73 +++++++++++++++++++++++++
>  1 files changed, 73 insertions(+), 0 deletions(-)
>  create mode 100644 Documentation/technical/api-ref-iteration.txt

> +Submodules
> +----------
> +
> +If you want to iterate the refs of a submodule you first need to call
> +
> +	add_submodule_odb(submodule)
> +
> +and test whether that succeeds.

Hmm, this should probably be explained a bit deeper or not at all. For
example, what is "submodule" here? A path to the submodule directory? The
name of submodule? What is the unwanted consequence of adding this extra
object database into your process (e.g. you can no longer tell if an
object exists in the superproject, as it may now come from the submodule's
object database)? Can you get rid of it? How does this function signal
failures? What is the symptom if you forget this call and used the
iteration in the submodule (e.g. "we do not see any ref"; "we see only
some ref but not all"; "the call crashes the process")?

> +
> +(Heiko Voigt)

Please drop this line for two reasons.

Initially I added these parenthesized names at the end for placeholder
pages to name people who are responsible for the _code_ the document
describes, so that the ones who help documentation would know who to nag
to get the necessary information. With your description, people who are
interested in documenting this API more would know that for_each_ref() and
friends are the topic and can find out whom to harrass.

Besides, with only two commits to refs.c, I doubt you would want to be the
primary source of information for other people to bug in order to enhance
the API description in this file.

Thanks.

[PATCH v2] add technical documentation about ref iteration

[Heiko Voigt]

Signed-off-by: Heiko Voigt <hvoigt@hvoigt.net>
---

Hi,

this is an update of the previous doc patch.

On Wed, Aug 03, 2011 at 12:10:37PM -0700, Junio C Hamano wrote:
> Heiko Voigt <hvoigt@hvoigt.net> writes:
> > +Submodules
> > +----------
> > +
> > +If you want to iterate the refs of a submodule you first need to call
> > +
> > +	add_submodule_odb(submodule)
> > +
> > +and test whether that succeeds.
> 
> Hmm, this should probably be explained a bit deeper or not at all. For
> example, what is "submodule" here? A path to the submodule directory? The
> name of submodule? What is the unwanted consequence of adding this extra
> object database into your process (e.g. you can no longer tell if an
> object exists in the superproject, as it may now come from the submodule's
> object database)? Can you get rid of it? How does this function signal
> failures? What is the symptom if you forget this call and used the
> iteration in the submodule (e.g. "we do not see any ref"; "we see only
> some ref but not all"; "the call crashes the process")?

I hope I answered all these questions in the patch below.

> 
> > +
> > +(Heiko Voigt)
> 
> Please drop this line for two reasons.

Dropped.

 Documentation/technical/api-ref-iteration.txt |   81 +++++++++++++++++++++++++
 1 files changed, 81 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/technical/api-ref-iteration.txt

diff --git a/Documentation/technical/api-ref-iteration.txt b/Documentation/technical/api-ref-iteration.txt
new file mode 100644
index 0000000..dbbea95
--- /dev/null
+++ b/Documentation/technical/api-ref-iteration.txt
@@ -0,0 +1,81 @@
+ref iteration API
+=================
+
+
+Iteration of refs is done by using an iterate function which will call a
+callback function for every ref. The callback function has this
+signature:
+
+	int handle_one_ref(const char *refname, const unsigned char *sha1,
+			   int flags, void *cb_data);
+
+There are different kinds of iterate functions which all take a
+callback of this type. The callback is then called for each found ref
+until the callback returns nonzero. The returned value is then also
+returned by the iterate function.
+
+Iteration functions
+-------------------
+
+* `head_ref()` just iterates the head ref.
+
+* `for_each_ref()` iterates all refs.
+
+* `for_each_ref_in()` iterates all refs which have a defined prefix and
+  strips that prefix from the passed variable refname.
+
+* `for_each_tag_ref()`, `for_each_branch_ref()`, `for_each_remote_ref()`,
+  `for_each_replace_ref()` iterate refs from the respective area.
+
+* `for_each_glob_ref()` iterates all refs that match the specified glob
+  pattern.
+
+* `for_each_glob_ref_in()` the previous and `for_each_ref_in()` combined.
+
+* `head_ref_submodule()`, `for_each_ref_submodule()`,
+  `for_each_ref_in_submodule()`, `for_each_tag_ref_submodule()`,
+  `for_each_branch_ref_submodule()`, `for_each_remote_ref_submodule()`
+  do the same as the functions descibed above but for a specified
+  submodule.
+
+* `for_each_rawref()` can be used to learn about broken ref and symref.
+
+* `for_each_reflog()` iterates each reflog file.
+
+Submodules
+----------
+
+If you want to iterate the refs of a submodule you first need to add the
+submodules object database. You can do this by a code-snippet like
+this:
+
+	const char *path = "path/to/submodule"
+	if (!add_submodule_odb(path))
+		die("Error submodule '%s' not populated.", path);
+
+`add_submodule_odb()` will return an non-zero value on success. If you
+do not do this you will get an error for each ref that it does not point
+to a valid object.
+
+Note: As a side-effect of this you can not safely assume that all
+objects you lookup are available in superproject. All submodule objects
+will be available the same way as the superprojects objects.
+
+Example:
+--------
+
+----
+static int handle_remote_ref(const char *refname,
+		const unsigned char *sha1, int flags, void *cb_data)
+{
+	struct strbuf *output = cb_data;
+	strbuf_addf(output, "%s\n", refname);
+	return 0;
+}
+
+...
+
+	struct strbuf output = STRBUF_INIT;
+	for_each_remote_ref(handle_remote_ref, &output);
+	printf("%s", output.buf);
+----
-- 
1.7.6.351.g9ce65.dirty

Re: [PATCH v2] add technical documentation about ref iteration

[Junio C Hamano]

Heiko Voigt <hvoigt@hvoigt.net> writes:

> Signed-off-by: Heiko Voigt <hvoigt@hvoigt.net>
> ---
>
> Hi,
>
> this is an update of the previous doc patch.

Looks very good; thanks.