# [PATCH] Revision waling documentation: fix a typo 11 messages from 2008-05-28 to 2008-05-31. Participants: Miklos Vajna, Johannes Schindelin, Junio C Hamano, Petr Baudis. Thread: https://gitlist.dev/t/13714 ## Miklos Vajna, 2008-05-28 22:08 Subject: [PATCH] Revision waling documentation: fix a typo Message-ID: <1212012495-5782-1-git-send-email-vmiklos@frugalware.org> URL: https://gitlist.dev/e/1212012495-5782-1-git-send-email-vmiklos%40frugalware.org ``` Signed-off-by: Miklos Vajna --- 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 , 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 ``` ## Johannes Schindelin, 2008-05-29 12:36 Subject: Re: [PATCH] Revision waling documentation: fix a typo Message-ID: URL: https://gitlist.dev/e/alpine.DEB.1.00.0805291336270.13507%40racer.site.net In-Reply-To: <1212012495-5782-1-git-send-email-vmiklos@frugalware.org> ``` Hi, you meant "walking" instead of "waling", right? ;-) Ciao, Dscho ``` ## Miklos Vajna, 2008-05-29 16:45 Subject: Re: [PATCH] Revision waling documentation: fix a typo Message-ID: <20080529164555.GP27724@genesis.frugalware.org> URL: https://gitlist.dev/e/20080529164555.GP27724%40genesis.frugalware.org In-Reply-To: ``` On Thu, May 29, 2008 at 01:36:44PM +0100, Johannes Schindelin wrote: > you meant "walking" instead of "waling", right? ;-) Heh, sure! Should I resend the patch fix a fixed title? ``` ## Junio C Hamano, 2008-05-29 18:35 Subject: Re: [PATCH] Revision waling documentation: fix a typo Message-ID: <7vzlq9nel7.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7vzlq9nel7.fsf%40gitster.siamese.dyndns.org In-Reply-To: <20080529164555.GP27724@genesis.frugalware.org> ``` Miklos Vajna writes: > On Thu, May 29, 2008 at 01:36:44PM +0100, Johannes Schindelin 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? ``` ## Miklos Vajna, 2008-05-29 21:56 Subject: [PATCH] Revision walking documentation: document most important functions Message-ID: <1212098185-8437-1-git-send-email-vmiklos@frugalware.org> URL: https://gitlist.dev/e/1212098185-8437-1-git-send-email-vmiklos%40frugalware.org In-Reply-To: <7vzlq9nel7.fsf@gitster.siamese.dyndns.org> ``` Unfortunately the list is not complete, but includes the essential ones. Signed-off-by: Miklos Vajna --- On Thu, May 29, 2008 at 11:35:16AM -0700, Junio C Hamano 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 , 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 ``` ## Junio C Hamano, 2008-05-29 23:41 Subject: Re: [PATCH] Revision walking documentation: document most important functions Message-ID: <7vmym8oezm.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7vmym8oezm.fsf%40gitster.siamese.dyndns.org In-Reply-To: <1212098185-8437-1-git-send-email-vmiklos@frugalware.org> ``` Miklos Vajna writes: > Unfortunately the list is not complete, but includes the essential ones. > > Signed-off-by: Miklos Vajna > --- > > On Thu, May 29, 2008 at 11:35:16AM -0700, Junio C Hamano 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) ``` ## Miklos Vajna, 2008-05-29 23:46 Subject: Re: [PATCH] Revision walking documentation: document most important functions Message-ID: <20080529234625.GU27724@genesis.frugalware.org> URL: https://gitlist.dev/e/20080529234625.GU27724%40genesis.frugalware.org In-Reply-To: <7vmym8oezm.fsf@gitster.siamese.dyndns.org> ``` On Thu, May 29, 2008 at 04:41:17PM -0700, Junio C Hamano 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. ;-) ``` ## Petr Baudis, 2008-05-30 00:20 Subject: Re: [PATCH] Revision walking documentation: document most important functions Message-ID: <20080530002006.GC18781@machine.or.cz> URL: https://gitlist.dev/e/20080530002006.GC18781%40machine.or.cz In-Reply-To: <20080529234625.GU27724@genesis.frugalware.org> ``` 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 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 ``` ## Junio C Hamano, 2008-05-30 00:29 Subject: Re: [PATCH] Revision walking documentation: document most important functions Message-ID: <7vej7kocrl.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7vej7kocrl.fsf%40gitster.siamese.dyndns.org In-Reply-To: <1212098185-8437-1-git-send-email-vmiklos@frugalware.org> ``` Miklos Vajna 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/; ``` ## Miklos Vajna, 2008-05-31 00:14 Subject: Re: [PATCH] Revision walking documentation: document most important functions Message-ID: <20080531001444.GB29404@genesis.frugalware.org> URL: https://gitlist.dev/e/20080531001444.GB29404%40genesis.frugalware.org In-Reply-To: <20080530002006.GC18781@machine.or.cz> ``` On Fri, May 30, 2008 at 02:20:06AM +0200, Petr Baudis 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. ;-) ``` ## Miklos Vajna, 2008-05-31 00:18 Subject: [PATCH] Revision walking documentation: document most important functions Message-ID: <1212193088-5420-1-git-send-email-vmiklos@frugalware.org> URL: https://gitlist.dev/e/1212193088-5420-1-git-send-email-vmiklos%40frugalware.org In-Reply-To: <7vej7kocrl.fsf@gitster.siamese.dyndns.org> ``` Unfortunately the list is not complete, but includes the essential ones. Signed-off-by: Miklos Vajna --- On Thu, May 29, 2008 at 05:29:18PM -0700, Junio C Hamano 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 , 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 ```