From: Junio C Hamano Date: Mon, 07 Aug 2006 23:49:19 GMT Subject: Re: [PATCH/RFC] gitweb: Great subroutines renaming Message-ID: <7vejvsyum8.fsf@assigned-by-dhcp.cox.net> In-Reply-To: Jakub Narebski writes: > Matthias Lederhofer has noticed that parsing all the tags in "summary" and > "tags" views, while we use only epoch/timestamp information to sort them > and discard most of parsed input, is bottleneck due to the fact that > usually number of tags is linear with history (version tags) and the fact > that for each tag is one invocation of git (one fork, two execs). Maybe we would want to expose for_each_ref somehow to the command level then. Looking at how "git branch" without any argument lists the branches, and how "git tag -l" lists the tags, it appears that we could benefit from such a command [*1*]. Of course doing it in Git.xs to make a single C level call is easy, but that would benefit only Perl scripts, so it is not a very good general solution. > So the new guidelines would be: > * git_get_ prefix for subroutines related to git repository > and returning single scalar (single value). > * git_read_ prefix for subroutines related to git repository, reading some > files or multiline output, and returning hash reference, or list > reference, or list. I would suggest to use git_get for both, unless there is a good reason to differenciate them, since I do not understand why you would want to differenciate one value vs multivalue. -- >8 -- [*1*] -- >8 -- [PATCH] git-show-refs Implementation is left as an exercise ;-) --- diff --git a/Documentation/git-show-refs.txt b/Documentation/git-show-refs.txt new file mode 100644 index 0000000..e2869e0 --- /dev/null +++ b/Documentation/git-show-refs.txt @@ -0,0 +1,96 @@ +git-show-refs(1) +================ + +NAME +---- +git-show-refs - Lists refs in various formats + +SYNOPSIS +-------- +'git-show-refs' [--count=] [--sort=] [--format=] [] + +DESCRIPTION +----------- + +Iterate over refs under `$GIT_DIR/refs` that match `` +and show them according to the given ``, after sorting +them according to the given ``. If `` is given, +stop after showing that many refs. + +OPTIONS +------- +:: + By default the command shows all refs that match + ``. This option makes it stop after showing + that many refs. + +:: + Comma separated field names to sort on. Prefix `-` to + sort in descending order of the value. When + unspecified, `name` is used. + +:: + A string that interpolates `%(field name)` from the + object pointed at by a ref being shown. When + unspecified, `%(name)` is used. + +:: + If given, the name of the ref is matched against this + using fnmatch(3). Refs that do not match the pattern + are not shown. + + +FIELD NAMES +----------- + +Various values from structured fields in referenced objects can +be used to interpolate into the resulting output, or as sort +keys. + +For all objects, the following names can be used: + +name:: + The name of the ref (the part after $GIT_DIR/refs/), + except that when `` is used, the leading fixed + string part of `` is stripped out. + +objecttype:: + The type of the object (`blob`, `tree`, `commit`, `tag`) + +objectsize:: + The size of the object (the same as `git-cat-file -s` reports). + +objectname:: + The object name (aka SHA-1). + +In addition, for commit and tag objects, the header field names +(`tree`, `parent`, `object`, `type`, and `tag`) can be used to +specify the value in the header field. Fields that have +name-email-date tuple as its value (`author`, `committer`, and +`tagger`) can be suffixed with `name`, `email`, and `date` to +extract the named component. The first line of a commit and tag +object can be referred to with `subject`, the remaining lines +with `body`, and both (including the typical blank line after +`subject`) with `contents`. + +Also a pseudo field name `ishead` can be used to check if the +ref is pointed by `$GIT_DIR/HEAD` pointer. The field +interpolates as "* " if true, otherwise an empty string. + +For sorting purposes, fields with numeric values sort in numeric +order (`objectsize`, `authordate`, `committerdate`, `taggerdate`). +All other fields are used to sort in their byte-value order. + + +EXAMPLES +-------- + +Show most recent 16 tags for consumption by gitweb:: + git-show-refs --count=16 --sort=-taggerdate,name \ + --format='%(taggerdate) %(name)\t%(tag)\t%(subject)' 'tags/*' + +`git-branch` without argument:: + git-show-refs --format='%(ishead)%(name)' 'heads/*' + +`git-tag -l`:: + git-show-refs tags/*