From: Junio C Hamano <gitster@pobox.com>
To: Miklos Vajna <vmiklos@frugalware.org>
Cc: git@vger.kernel.org, Johannes Schindelin <Johannes.Schindelin@gmx.de>
Subject: Re: [PATCH] Revision walking documentation: document most important functions
Date: Thu, 29 May 2008 17:29:18 -0700 [thread overview]
Message-ID: <7vej7kocrl.fsf@gitster.siamese.dyndns.org> (raw)
In-Reply-To: <1212098185-8437-1-git-send-email-vmiklos@frugalware.org> (Miklos Vajna's message of "Thu, 29 May 2008 23:56:25 +0200")
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/;
next prev parent reply other threads:[~2008-05-30 0:30 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2008-05-28 22:08 [PATCH] Revision waling documentation: fix a typo Miklos Vajna
2008-05-29 12:36 ` Johannes Schindelin
2008-05-29 16:45 ` Miklos Vajna
2008-05-29 18:35 ` Junio C Hamano
2008-05-29 21:56 ` [PATCH] Revision walking documentation: document most important functions Miklos Vajna
2008-05-29 23:41 ` Junio C Hamano
2008-05-29 23:46 ` Miklos Vajna
2008-05-30 0:20 ` Petr Baudis
2008-05-31 0:14 ` Miklos Vajna
2008-05-30 0:29 ` Junio C Hamano [this message]
2008-05-31 0:18 ` Miklos Vajna
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=7vej7kocrl.fsf@gitster.siamese.dyndns.org \
--to=gitster@pobox.com \
--cc=Johannes.Schindelin@gmx.de \
--cc=git@vger.kernel.org \
--cc=vmiklos@frugalware.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).