git/gitweb - feature request: Add description to the branches.

Hi:

First, thank you for this great tool.

One thing I'm missing is a way to describe a branch. It can be done in the $GIT_DIR/description, the first line for the whole repository and the rest for the branches. So description file for the git.git repository could be:

[description]
The core git plumbing
pu: Proposed updates
rc: Release candidate
todo: Todo list
[/description]

And it can be added to the gitweb tool.

Thanks.

Santi

Santi Béjar wrote:
[...]

Having somewhere to describe the intent of a branch would be a useful convention. But I think the descriptions should be in separate files; one for each branch and one for the repository as a whole.

That way it would be possible to have long, multi-line descriptions of the repository and branches with the tools displaying just the first line unless more information is requested; like gitk and gitkweb do with commit messages.

An unrelated gitweb feature request: include a timestamp near the top of the projects page so that I don't have to try to remember when I last reloaded the page. TZ=UTC preferred.

GIT Repository Annotation Convention
====================================

GIT repositories can benefit from descriptions of /intent/ for portions of the repository. This document formalizes a method to store those descriptions in the repository.

Annotations
------------
Annotations are UTF8 text files. Each text starts with a one line summary, optionally followed by a blank line and a longer, more detailed description.

Annotations describe the /intended/ use or contents of the repository portion described. For instance, a branch is defined by a head ref; the annotation for that branch would describe what that branch is intended to hold, how to interpret and/or use the stored state, etc.

Naming and Directory Structure
------------------------------
Annotations are named by appending ".txt" to the basename of the repository component it describes, and by appending ".dir" to each directory patch component leading to the repository component from $GIT_DIR, and by prepending "annotations/" to the annotation pathname.

The use of the ".txt" and ".dir" suffixes is to allow for descriptions of hierarchical structures (directories) and well as specific components (files).

Missing annotations are ignored.

The file "$GIT_DIR/description", used by gitweb and other tools, becomes a symbolic link to "$GIT_DIR/annotations/description.txt".

Example Layout
--------------
$GIT_DIR/

	...
	annotations/
		...
		annotations.txt
		...
		description.txt
		...
		refs.dir/
			...
			heads.dir/
				<head dir 1>.dir/
					<head name 1.1>.txt
					...
					<head name 1.M>.txt
				<head dir 1>.txt
				...
				<head dir N>.dir/
					<head name N.1>.txt
					...
					<head name N.P>.txt
				<head name 1>.txt
				...
				<head name Q>.txt
			...
			tags.dir/
				<tag name 1>.txt
				...
				<tag name T>.txt
			...
	...
	description -> annotations/description.txt
	...

--

[...]

I'm not proposing any new tools, just a convention that existing tools or tools that others may create can adopt to provide information to a repositories users. Some existing tools that could use the annotations are:
git-branch
git-show-branch
gitweb
There are likely others.

Like any other file under $GIT_DIR, these files are not automatically versioned. Rather, each repository maintainer, needs to decide how a repository's meta-data (project meta-meta-data) is tracked or generated.

I suspect you can do the same without .dir but only with .txt.

Are you saying I can't name a branch "foo.txt"? Or have the following branches?

$GIT_DIR/refs/head/WidgetSoft/Blue
$GIT_DIR/refs/head/WidgetSoft/Red
$GIT_DIR/refs/head/WidgetSoft.txt/Blue
$GIT_DIR/refs/head/WidgetSoft.txt/Red

Think about a directory containing directories "foo" and "foo.txt":

With ".dir":

	foo.dir/
		...
	foo.txt
	foo.txt.dir/
		...
	foo.txt.txt

Without ".dir":

	foo/
		...
==>	foo.txt
==>	foo.txt/
		...
	foo.txt.txt

Can you tell us why you're using extensions in the first place?

I propose using no extensions whatsoever: simply mirror the refs/ tree.

Matthias Urlichs   |   {M:U} IT Design @ m-u-it.de   |  [email protected]
Disclaimer: The quote was selected randomly. Really. | http://smurf.noris.de
 - -
The rich get rich, and the poor get poorer.
The haves get more, the have-nots die.

The extensions allow the annotation of directories as well as files. That's something that can't be done if extensions are not used.

OTOH, for git directories are only there to organize files, they have no independent existence.

Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                     Fono: +56 32 654431
Universidad Tecnica Federico Santa Maria              +56 32 654239
Casilla 110-V, Valparaiso, Chile                Fax:  +56 32 797513

IMHO, that is the sort of information that's best saved in the "how is our source organized" section of your ./HACKING file.

Or you can simply use reiserfs4, with its files-are-directories feature. (*ducks and runs*)

Matthias Urlichs   |   {M:U} IT Design @ m-u-it.de   |  [email protected]
Disclaimer: The quote was selected randomly. Really. | http://smurf.noris.de
 - -
Ask yourself whether you are happy and you cease to be so.

This reminds me of somebody else wanting to have 'motd' in git-daemon. Once we have a common data format we could also serve this information from there, and possibly from 'git fetch --motd'; pass that to 'git-peek-remote --motd' for git and ssh transports, and do something else using curl for http transport.

Anybody interested? I think the git-daemon side would be the cleanest if we introduce a new program to format the motd information and send it out, instead of attempting to enhance git-upload-pack protocol; I do not think the latter can be done in a backward compatible way.