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.

A Large Angry SCM <gitzilla@gmail.com> writes:

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.

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
	...

--

A Large Angry SCM <gitzilla@gmail.com> writes:

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

Junio C Hamano wrote:

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

Hi, A Large Angry SCM wrote:

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 wrote:

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

Hi, A Large Angry SCM wrote:

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*)

Chuck Lever wrote:

[...]

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.

Junio C Hamano wrote:

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