Jakub Narebski <jnareb@xxxxxxxxx> 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=<max>] [--sort=<sortkeys>] [--format=<format>] [<pattern>] + +DESCRIPTION +----------- + +Iterate over refs under `$GIT_DIR/refs` that match `<pattern>` +and show them according to the given `<format>`, after sorting +them according to the given `<sortkeys>`. If `<max>` is given, +stop after showing that many refs. + +OPTIONS +------- +<max>:: + By default the command shows all refs that match + `<pattern>`. This option makes it stop after showing + that many refs. + +<sortkeys>:: + Comma separated field names to sort on. Prefix `-` to + sort in descending order of the value. When + unspecified, `name` is used. + +<format>:: + A string that interpolates `%(field name)` from the + object pointed at by a ref being shown. When + unspecified, `%(name)` is used. + +<pattern>:: + 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 `<pattern>` is used, the leading fixed + string part of `<pattern>` 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/* - : send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html