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

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

[Santi Béjar]

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

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

[A Large Angry SCM]

Santi Béjar wrote:
[...]
> 
>         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.

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.

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

[Junio C Hamano]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=iso-2022-jp-2, Size: 1332 bytes --]

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

> Santi B^[.A^[Nijar wrote:
> [...]
>>         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.
>
> 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.

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.

[RFC] GIT Repository Annotation Convention

[A Large Angry SCM]

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

--

Re: [RFC] GIT Repository Annotation Convention

[Junio C Hamano]

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

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

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

Re: [RFC] GIT Repository Annotation Convention

[A Large Angry SCM]

Junio C Hamano wrote:
> A Large Angry SCM <gitzilla@gmail.com> writes:
> 
>>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.
> 
> I suspect you can do the same without .dir but only with .txt.

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

Re: [RFC] GIT Repository Annotation Convention

[Matthias Urlichs]

Hi, A Large Angry SCM wrote:

> Think about a directory containing directories "foo" and "foo.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   |  smurf@smurf.noris.de
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.

Re: [RFC] GIT Repository Annotation Convention

[A Large Angry SCM]

Matthias Urlichs wrote:
> Hi, A Large Angry SCM wrote:
> 
>>Think about a directory containing directories "foo" and "foo.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.
> 

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

Re: [RFC] GIT Repository Annotation Convention

[Horst von Brand]

A Large Angry SCM <gitzilla@gmail.com> wrote:
> Matthias Urlichs wrote:
> > Hi, A Large Angry SCM wrote:
> >
> >>Think about a directory containing directories "foo" and "foo.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.

> 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

Re: [RFC] GIT Repository Annotation Convention

[Matthias Urlichs]

Hi, A Large Angry SCM wrote:

>> I propose using no extensions whatsoever: simply mirror the refs/ tree.
> 
> The extensions allow the annotation of directories as well as files. 
> That's something that can't be done if extensions are not used.

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   |  smurf@smurf.noris.de
Disclaimer: The quote was selected randomly. Really. | http://smurf.noris.de
 - -
Ask yourself whether you are happy and you cease to be so.

Re: [RFC] GIT Repository Annotation Convention

[A Large Angry SCM]

Junio C Hamano wrote:
> A Large Angry SCM <gitzilla@gmail.com> writes:
> 
>>Junio C Hamano wrote:
>>>A Large Angry SCM <gitzilla@gmail.com> writes:
>>>
>>>>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.
>>>I suspect you can do the same without .dir but only with .txt.
>>Think about a directory containing directories "foo" and "foo.txt":
> 
> And where do you see foo.txt under $GIT_DIR/ hierarchy?

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

Re: [RFC] GIT Repository Annotation Convention

[A Large Angry SCM]

Chuck Lever wrote:
> yay!  are you also proposing some git tools to deal with these?  it 
> would be great to have some version control (keep these like generation 
> files so we can see the history of revisions).
> 
> A Large Angry SCM wrote:
>> GIT Repository Annotation Convention
[...]

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.