# git/gitweb - feature request: Add description to the branches. 11 messages from 2005-09-06 to 2005-09-13. Participants: Santi Béjar, A Large Angry SCM, Junio C Hamano, Matthias Urlichs. Thread: https://gitlist.dev/t/1736 ## Santi Béjar, 2005-09-06 13:21 Subject: git/gitweb - feature request: Add description to the branches. Message-ID: <87ll2aib73.fsf@gmail.com> URL: https://gitlist.dev/e/87ll2aib73.fsf%40gmail.com ``` 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 ``` ## A Large Angry SCM, 2005-09-06 14:33 Subject: Re: git/gitweb - feature request: Add description to the branches. Message-ID: <431DA8CD.9060009@gmail.com> URL: https://gitlist.dev/e/431DA8CD.9060009%40gmail.com In-Reply-To: <87ll2aib73.fsf@gmail.com> ``` 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. ``` ## Junio C Hamano, 2005-09-08 01:27 Subject: Re: git/gitweb - feature request: Add description to the branches. Message-ID: <7vll281h7k.fsf@assigned-by-dhcp.cox.net> URL: https://gitlist.dev/e/7vll281h7k.fsf%40assigned-by-dhcp.cox.net In-Reply-To: <431DA8CD.9060009@gmail.com> ``` A Large Angry SCM writes: > 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. 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. ``` ## A Large Angry SCM, 2005-09-08 16:03 Subject: [RFC] GIT Repository Annotation Convention Message-ID: <432060B8.6080408@gmail.com> URL: https://gitlist.dev/e/432060B8.6080408%40gmail.com In-Reply-To: <431DA8CD.9060009@gmail.com> ``` 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/ .dir/ .txt ... .txt .txt ... .dir/ .txt ... .txt .txt ... .txt ... tags.dir/ .txt ... .txt ... ... description -> annotations/description.txt ... -- ``` ## Junio C Hamano, 2005-09-08 18:00 Subject: Re: [RFC] GIT Repository Annotation Convention Message-ID: <7vr7bzv3r2.fsf@assigned-by-dhcp.cox.net> URL: https://gitlist.dev/e/7vr7bzv3r2.fsf%40assigned-by-dhcp.cox.net In-Reply-To: <432060B8.6080408@gmail.com> ``` A Large Angry SCM 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. ``` ## A Large Angry SCM, 2005-09-08 18:32 Subject: Re: [RFC] GIT Repository Annotation Convention Message-ID: <432083C2.6080704@gmail.com> URL: https://gitlist.dev/e/432083C2.6080704%40gmail.com In-Reply-To: <43207B68.5020204@citi.umich.edu> ``` 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. ``` ## A Large Angry SCM, 2005-09-08 18:58 Subject: Re: [RFC] GIT Repository Annotation Convention Message-ID: <432089D5.7000102@gmail.com> URL: https://gitlist.dev/e/432089D5.7000102%40gmail.com In-Reply-To: <7vr7bzv3r2.fsf@assigned-by-dhcp.cox.net> ``` Junio C Hamano wrote: > A Large Angry SCM 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 ``` ## A Large Angry SCM, 2005-09-09 14:24 Subject: Re: [RFC] GIT Repository Annotation Convention Message-ID: <43219B30.4040308@gmail.com> URL: https://gitlist.dev/e/43219B30.4040308%40gmail.com In-Reply-To: <7vvf1bq64t.fsf@assigned-by-dhcp.cox.net> ``` Junio C Hamano wrote: > A Large Angry SCM writes: > >>Junio C Hamano wrote: >>>A Large Angry SCM 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 ``` ## Matthias Urlichs, 2005-09-11 16:37 Subject: Re: [RFC] GIT Repository Annotation Convention Message-ID: URL: https://gitlist.dev/e/pan.2005.09.11.16.37.20.483911%40smurf.noris.de In-Reply-To: <432089D5.7000102@gmail.com> ``` 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. ``` ## A Large Angry SCM, 2005-09-11 18:08 Subject: Re: [RFC] GIT Repository Annotation Convention Message-ID: <43247298.2010500@gmail.com> URL: https://gitlist.dev/e/43247298.2010500%40gmail.com In-Reply-To: ``` 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. ``` ## Matthias Urlichs, 2005-09-13 17:46 Subject: Re: [RFC] GIT Repository Annotation Convention Message-ID: URL: https://gitlist.dev/e/pan.2005.09.13.17.45.59.307129%40smurf.noris.de In-Reply-To: <43247298.2010500@gmail.com> ``` 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. ```