[PATCH] Revision waling documentation: fix a typo

[PATCH] Revision waling documentation: fix a typo

[Miklos Vajna]

Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>
---
 Documentation/technical/api-revision-walking.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/technical/api-revision-walking.txt b/Documentation/technical/api-revision-walking.txt
index 01a2455..c0797d3 100644
--- a/Documentation/technical/api-revision-walking.txt
+++ b/Documentation/technical/api-revision-walking.txt
@@ -4,6 +4,6 @@ revision walking API
 Talk about <revision.h>, things like:
 
 * two diff_options, one for path limiting, another for output;
-* calling sequence: init_revisions(), setup_revsions(), get_revision();
+* calling sequence: init_revisions(), setup_revisions(), get_revision();
 
 (Linus, JC, Dscho)
-- 
1.5.6.rc0.dirty

Re: [PATCH] Revision waling documentation: fix a typo

[Johannes Schindelin]

Hi,

you meant "walking" instead of "waling", right? ;-)

Ciao,
Dscho

Re: [PATCH] Revision waling documentation: fix a typo

[Miklos Vajna]

[-- Attachment #1: Type: text/plain, Size: 209 bytes --]

On Thu, May 29, 2008 at 01:36:44PM +0100, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:
> you meant "walking" instead of "waling", right? ;-)

Heh, sure! Should I resend the patch fix a fixed title?

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: [PATCH] Revision waling documentation: fix a typo

[Junio C Hamano]

Miklos Vajna <vmiklos@frugalware.org> writes:

> On Thu, May 29, 2008 at 01:36:44PM +0100, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:
>> you meant "walking" instead of "waling", right? ;-)
>
> Heh, sure! Should I resend the patch fix a fixed title?

Please don't.

I do not want to apply a patch _from you_ to that file unless it actually
adds meat to the description --- I know you know git better than doing
just a typofix to a placeholder.

Also why did I have to fix my To: header when I tried to respond to your
message?

[PATCH] Revision walking documentation: document most important functions

[Miklos Vajna]

Unfortunately the list is not complete, but includes the essential ones.

Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>
---

On Thu, May 29, 2008 at 11:35:16AM -0700, Junio C Hamano <gitster@pobox.com> wrote:
> I do not want to apply a patch _from you_ to that file unless it
> actually
> adds meat to the description --- I know you know git better than doing
> just a typofix to a placeholder.

Here is a start. To be honest I never used the functions I did not
document, so I don't have too much idea what they do (not counting
reading the source ;-) ), so I thought it's better if I leave them
excluded from the list.

> Also why did I have to fix my To: header when I tried to respond to
> your
> message?

Hm, I sent the patch using git-send-email, adding the Cc line manually
and having your address in sendemail.to, so I don't know exactly what
can be special in this setup.

 Documentation/technical/api-revision-walking.txt |   57 +++++++++++++++++++++-
 1 files changed, 56 insertions(+), 1 deletions(-)

diff --git a/Documentation/technical/api-revision-walking.txt b/Documentation/technical/api-revision-walking.txt
index 01a2455..f073ee3 100644
--- a/Documentation/technical/api-revision-walking.txt
+++ b/Documentation/technical/api-revision-walking.txt
@@ -1,9 +1,64 @@
 revision walking API
 ====================
 
+The revision walking API offers functions to build a list of revisions
+and then iterate over that list.
+
+The walking API has a given calling sequence: first you need to
+initialize a rev_info structure, then add revisions to control what kind
+of revision list do you want to get, finally you can iterate over the
+revision list.
+
+Functions
+---------
+
+`init_revisions`::
+
+	Initialize a rev_info structure with default values. The second
+	parameter may be NULL or can be prefix path, and then the `.prefix`
+	variable will be set to it. This is typically the first function you
+	want to call when you want to deal with a revision list. After calling
+	this function, you are free to customize options, like set
+	`.ignore_merges` to 0 if you don't want to ignore merges, and so on. See
+	`revision.h` for a complete list of available options.
+
+`add_pending_object`::
+
+	This function can be used if you want to add commit objects as revision
+	information. You can use the `UNINTERESTING` object flag to indicate if
+	you want to include or exclude the given commit (and commits reachable
+	from the given commit) from the revision list.
++
+NOTE: If you have the commits as a string list then you probably want to
+use setup_revisions(), instead of parsing each string and using this
+function.
+
+`setup_revisions`::
+
+	Parse revision information, filling in the `rev_info` structure, and
+	removing the used arguments from the argument list. Returns the number
+	of arguments left that weren't recognized, which are also moved to the
+	head of the argument list. The last parameter is used in case no
+	parameter given by the first two arguments.
+
+`prepare_revision_walk`::
+
+	Prepares the rev_info structure for a walk. You should check if it
+	returns any error (positive return code) and if it does not, you can
+	start using get_revision() to do the iteration.
+
+`get_revision`::
+
+	Takes a pointer to a `rev_info` structure and iterates over it,
+	returning a `struct commit *` each time you call it. The end of the
+	revision list is indicated by returning a NULL pointer.
+
+Data structures
+---------------
+
 Talk about <revision.h>, things like:
 
 * two diff_options, one for path limiting, another for output;
-* calling sequence: init_revisions(), setup_revsions(), get_revision();
+* remaining functions;
 
 (Linus, JC, Dscho)
-- 
1.5.6.rc0.dirty

Re: [PATCH] Revision walking documentation: document most important functions

[Junio C Hamano]

Miklos Vajna <vmiklos@frugalware.org> writes:

> Unfortunately the list is not complete, but includes the essential ones.
>
> Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>
> ---
>
> On Thu, May 29, 2008 at 11:35:16AM -0700, Junio C Hamano <gitster@pobox.com> wrote:
>> I do not want to apply a patch _from you_ to that file unless it
>> actually
>> adds meat to the description --- I know you know git better than doing
>> just a typofix to a placeholder.
>
> Here is a start. To be honest I never used the functions I did not
> document, so I don't have too much idea what they do (not counting
> reading the source ;-) ), so I thought it's better if I leave them
> excluded from the list.
>
>> Also why did I have to fix my To: header when I tried to respond to
>> your
>> message?
>
> Hm, I sent the patch using git-send-email,...

I do not think so.  You used 

    User-Agent: Mutt/1.5.17 (2007-11-01)

Re: [PATCH] Revision walking documentation: document most important functions

[Miklos Vajna]

[-- Attachment #1: Type: text/plain, Size: 380 bytes --]

On Thu, May 29, 2008 at 04:41:17PM -0700, Junio C Hamano <gitster@pobox.com> wrote:
> > Hm, I sent the patch using git-send-email,...
> 
> I do not think so.  You used 
> 
>     User-Agent: Mutt/1.5.17 (2007-11-01)

Oh, I misunderstood you. I was talking about the patch itself. Though
the other mail seem to be pretty usual as well, so it's still a mystery
for me. ;-)

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: [PATCH] Revision walking documentation: document most important functions

[Petr Baudis]

On Fri, May 30, 2008 at 01:46:25AM +0200, Miklos Vajna wrote:
> On Thu, May 29, 2008 at 04:41:17PM -0700, Junio C Hamano <gitster@pobox.com> wrote:
> > > Hm, I sent the patch using git-send-email,...
> > 
> > I do not think so.  You used 
> > 
> >     User-Agent: Mutt/1.5.17 (2007-11-01)
> 
> Oh, I misunderstood you. I was talking about the patch itself. Though
> the other mail seem to be pretty usual as well, so it's still a mystery
> for me. ;-)

You probably have git@vger.kernel.org configured as a list in your
~/.muttrc and followup_to set to yes (the default) - so Mutt generates a
Mail-Followup-To header omitting you so that you won't receive the
replies twice.

Incidentally, I have an opposite problem; when someone sends a reply
both to me and to git@, I never get the mailing list copy.

-- 
				Petr "Pasky" Baudis
Whatever you can do, or dream you can, begin it.
Boldness has genius, power, and magic in it.	-- J. W. von Goethe

Re: [PATCH] Revision walking documentation: document most important functions

[Junio C Hamano]

Miklos Vajna <vmiklos@frugalware.org> writes:

> Unfortunately the list is not complete, but includes the essential ones.
> ...
> Here is a start. To be honest I never used the functions I did not
> document, so I don't have too much idea what they do (not counting
> reading the source ;-) ), so I thought it's better if I leave them
> excluded from the list.

It's a good start.  Thanks.

>  revision walking API
>  ====================
>  
> +The revision walking API offers functions to build a list of revisions
> +and then iterate over that list.

> +The walking API has a given calling sequence: first you need to
> +initialize a rev_info structure, then add revisions to control what kind
> +of revision list do you want to get, finally you can iterate over the
> +revision list.

I think this paragraph is easier to read if it is in its own subsection
"Calling Sequence" (see api-diff.txt for an example).

> +Functions
> +---------
> +
> +`init_revisions`::
> +
> +	Initialize a rev_info structure with default values. The second
> +	parameter may be NULL or can be prefix path, and then the `.prefix`
> +	variable will be set to it. This is typically the first function you
> +	want to call when you want to deal with a revision list. After calling
> +	this function, you are free to customize options, like set
> +	`.ignore_merges` to 0 if you don't want to ignore merges, and so on. See
> +	`revision.h` for a complete list of available options.

Traversal options are numerous and complex, so I agree that it makes sense
to refer the reader elsewhere.  We can start with "revision.h", and extend
this documentation by adding a separate section on it.

> +`add_pending_object`::
> +
> +	This function can be used if you want to add commit objects as revision
> +	information. You can use the `UNINTERESTING` object flag to indicate if
> +	you want to include or exclude the given commit (and commits reachable
> +	from the given commit) from the revision list.
> ++
> +NOTE: If you have the commits as a string list then you probably want to
> +use setup_revisions(), instead of parsing each string and using this
> +function.
> +
> +`setup_revisions`::
> +
> +	Parse revision information, filling in the `rev_info` structure, and
> +	removing the used arguments from the argument list. Returns the number
> +	of arguments left that weren't recognized, which are also moved to the
> +	head of the argument list. The last parameter is used in case no
> +	parameter given by the first two arguments.
> +
> +`prepare_revision_walk`::
> +
> +	Prepares the rev_info structure for a walk. You should check if it
> +	returns any error (positive return code) and if it does not, you can

s/positive/non-zero/;

Re: [PATCH] Revision walking documentation: document most important functions

[Miklos Vajna]

[-- Attachment #1: Type: text/plain, Size: 522 bytes --]

On Fri, May 30, 2008 at 02:20:06AM +0200, Petr Baudis <pasky@suse.cz> wrote:
> You probably have git@vger.kernel.org configured as a list in your
> ~/.muttrc and followup_to set to yes (the default) - so Mutt generates a
> Mail-Followup-To header omitting you so that you won't receive the
> replies twice.

Ah, yes, this is exactly the case, thanks for the hint. Given that most
mailers ignore that header (so I receive duplicated mails anyway), I
just disabled followup_to, hopefully this makes Junio's setup happy. ;-)

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

[PATCH] Revision walking documentation: document most important functions

[Miklos Vajna]

Unfortunately the list is not complete, but includes the essential ones.

Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>
---

On Thu, May 29, 2008 at 05:29:18PM -0700, Junio C Hamano <gitster@pobox.com> wrote:
> I think this paragraph is easier to read if it is in its own
> subsection
> "Calling Sequence" (see api-diff.txt for an example).

Done.

> > +`prepare_revision_walk`::
> > +
> > +   Prepares the rev_info structure for a walk. You should check if
> > it
> > +   returns any error (positive return code) and if it does not, you
> > can
>
> s/positive/non-zero/;

Fixed.

 Documentation/technical/api-revision-walking.txt |   60 +++++++++++++++++++++-
 1 files changed, 59 insertions(+), 1 deletions(-)

diff --git a/Documentation/technical/api-revision-walking.txt b/Documentation/technical/api-revision-walking.txt
index 01a2455..996da05 100644
--- a/Documentation/technical/api-revision-walking.txt
+++ b/Documentation/technical/api-revision-walking.txt
@@ -1,9 +1,67 @@
 revision walking API
 ====================
 
+The revision walking API offers functions to build a list of revisions
+and then iterate over that list.
+
+Calling sequence
+----------------
+
+The walking API has a given calling sequence: first you need to
+initialize a rev_info structure, then add revisions to control what kind
+of revision list do you want to get, finally you can iterate over the
+revision list.
+
+Functions
+---------
+
+`init_revisions`::
+
+	Initialize a rev_info structure with default values. The second
+	parameter may be NULL or can be prefix path, and then the `.prefix`
+	variable will be set to it. This is typically the first function you
+	want to call when you want to deal with a revision list. After calling
+	this function, you are free to customize options, like set
+	`.ignore_merges` to 0 if you don't want to ignore merges, and so on. See
+	`revision.h` for a complete list of available options.
+
+`add_pending_object`::
+
+	This function can be used if you want to add commit objects as revision
+	information. You can use the `UNINTERESTING` object flag to indicate if
+	you want to include or exclude the given commit (and commits reachable
+	from the given commit) from the revision list.
++
+NOTE: If you have the commits as a string list then you probably want to
+use setup_revisions(), instead of parsing each string and using this
+function.
+
+`setup_revisions`::
+
+	Parse revision information, filling in the `rev_info` structure, and
+	removing the used arguments from the argument list. Returns the number
+	of arguments left that weren't recognized, which are also moved to the
+	head of the argument list. The last parameter is used in case no
+	parameter given by the first two arguments.
+
+`prepare_revision_walk`::
+
+	Prepares the rev_info structure for a walk. You should check if it
+	returns any error (non-zero return code) and if it does not, you can
+	start using get_revision() to do the iteration.
+
+`get_revision`::
+
+	Takes a pointer to a `rev_info` structure and iterates over it,
+	returning a `struct commit *` each time you call it. The end of the
+	revision list is indicated by returning a NULL pointer.
+
+Data structures
+---------------
+
 Talk about <revision.h>, things like:
 
 * two diff_options, one for path limiting, another for output;
-* calling sequence: init_revisions(), setup_revsions(), get_revision();
+* remaining functions;
 
 (Linus, JC, Dscho)
-- 
1.5.6.rc0.dirty