{"thread":{"id":"1736","subject":"git/gitweb - feature request: Add description to the branches.","startedAt":"2005-09-06T13:21:20Z","lastAt":"2005-09-13T17:46:00Z","messageCount":11,"participants":["Santi Béjar","A Large Angry SCM","Junio C Hamano","Matthias Urlichs"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"8125","messageId":"87ll2aib73.fsf@gmail.com","threadId":"1736","inReplyTo":null,"subject":"git/gitweb - feature request: Add description to the branches.","fromName":"Santi Béjar","fromEmail":"sbejar@gmail.com","sentAt":"2005-09-06T13:21:20Z","receivedAt":"2005-09-06T13:21:20Z","isPatch":false,"sender":{"key":"santi@agolina.net","avatar":null},"body":"Hi:\n\n        First, thank you for this great tool.\n\n        One thing I'm missing is a way to describe a branch. It can be\n        done in the $GIT_DIR/description, the first line for the whole\n        repository and the rest for the branches. So description file\n        for the git.git repository could be:\n\n[description]\nThe core git plumbing\npu: Proposed updates\nrc: Release candidate\ntodo: Todo list\n[/description]\n\n        And it can be added to the gitweb tool.\n\n        Thanks.\n\n        Santi\n"},{"id":"8126","messageId":"431DA8CD.9060009@gmail.com","threadId":"1736","inReplyTo":"87ll2aib73.fsf@gmail.com","subject":"Re: git/gitweb - feature request: Add description to the branches.","fromName":"A Large Angry SCM","fromEmail":"gitzilla@gmail.com","sentAt":"2005-09-06T14:33:49Z","receivedAt":"2005-09-06T14:33:49Z","isPatch":false,"sender":{"key":"gitzilla@gmail.com","avatar":"https://gravatar.com/avatar/354625c442439908ff3dd99757dee330e29e9df7847472384faf7a00add247fb?d=mp&s=160"},"body":"Santi Béjar wrote:\n[...]\n> \n>         One thing I'm missing is a way to describe a branch. It can be\n>         done in the $GIT_DIR/description, the first line for the whole\n>         repository and the rest for the branches. So description file\n>         for the git.git repository could be:\n> \n> [description]\n> The core git plumbing\n> pu: Proposed updates\n> rc: Release candidate\n> todo: Todo list\n> [/description]\n> \n>         And it can be added to the gitweb tool.\n\nHaving somewhere to describe the intent of a branch would be a useful \nconvention. But I think the descriptions should be in separate files; \none for each branch and one for the repository as a whole.\n\nThat way it would be possible to have long, multi-line descriptions of \nthe repository and branches with the tools displaying just the first \nline unless more information is requested; like gitk and gitkweb do with \ncommit messages.\n\nAn unrelated gitweb feature request: include a timestamp near the top of \nthe projects page so that I don't have to try to remember when I last \nreloaded the page. TZ=UTC preferred.\n"},{"id":"8182","messageId":"7vll281h7k.fsf@assigned-by-dhcp.cox.net","threadId":"1736","inReplyTo":"431DA8CD.9060009@gmail.com","subject":"Re: git/gitweb - feature request: Add description to the branches.","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2005-09-08T01:27:59Z","receivedAt":"2005-09-08T01:27:59Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"A Large Angry SCM <gitzilla@gmail.com> writes:\n\n> Santi Béjar wrote:\n> [...]\n>>         One thing I'm missing is a way to describe a branch. It can\n>> be\n>>         done in the $GIT_DIR/description, the first line for the whole\n>>         repository and the rest for the branches. So description file\n>>         for the git.git repository could be:\n>> [description]\n>> The core git plumbing\n>> pu: Proposed updates\n>> rc: Release candidate\n>> todo: Todo list\n>> [/description]\n>>         And it can be added to the gitweb tool.\n>\n> Having somewhere to describe the intent of a branch would be a useful \n> convention. But I think the descriptions should be in separate files; \n> one for each branch and one for the repository as a whole.\n\nThis reminds me of somebody else wanting to have 'motd' in\ngit-daemon.  Once we have a common data format we could also\nserve this information from there, and possibly from\n'git fetch --motd'; pass that to 'git-peek-remote --motd' for git\nand ssh transports, and do something else using curl for http\ntransport.\n\nAnybody interested?  I think the git-daemon side would be the\ncleanest if we introduce a new program to format the motd\ninformation and send it out, instead of attempting to enhance\ngit-upload-pack protocol; I do not think the latter can be\ndone in a backward compatible way.\n"},{"id":"8197","messageId":"432060B8.6080408@gmail.com","threadId":"1736","inReplyTo":"431DA8CD.9060009@gmail.com","subject":"[RFC] GIT Repository Annotation Convention","fromName":"A Large Angry SCM","fromEmail":"gitzilla@gmail.com","sentAt":"2005-09-08T16:03:04Z","receivedAt":"2005-09-08T16:03:04Z","isPatch":false,"sender":{"key":"gitzilla@gmail.com","avatar":"https://gravatar.com/avatar/354625c442439908ff3dd99757dee330e29e9df7847472384faf7a00add247fb?d=mp&s=160"},"body":"GIT Repository Annotation Convention\n====================================\n\nGIT repositories can benefit from descriptions of /intent/ for portions\nof the repository. This document formalizes a method to store those\ndescriptions in the repository.\n\nAnnotations\n------------\nAnnotations are UTF8 text files. Each text starts with a one line\nsummary, optionally followed by a blank line and a longer, more detailed\ndescription.\n\nAnnotations describe the /intended/ use or contents of the repository\nportion described. For instance, a branch is defined by a head ref; the\nannotation for that branch would describe what that branch is intended\nto hold, how to interpret and/or use the stored state, etc.\n\nNaming and Directory Structure\n------------------------------\nAnnotations are named by appending \".txt\" to the basename of the\nrepository component it describes, and by appending \".dir\" to each\ndirectory patch component leading to the repository component from\n$GIT_DIR, and by prepending \"annotations/\" to the annotation pathname.\n\nThe use of the \".txt\" and \".dir\" suffixes is to allow for descriptions\nof hierarchical structures (directories) and well as specific components\n(files).\n\nMissing annotations are ignored.\n\nThe file \"$GIT_DIR/description\", used by gitweb and other tools, becomes\na symbolic link to \"$GIT_DIR/annotations/description.txt\".\n\nExample Layout\n--------------\n$GIT_DIR/\n\t...\n\tannotations/\n\t\t...\n\t\tannotations.txt\n\t\t...\n\t\tdescription.txt\n\t\t...\n\t\trefs.dir/\n\t\t\t...\n\t\t\theads.dir/\n\t\t\t\t<head dir 1>.dir/\n\t\t\t\t\t<head name 1.1>.txt\n\t\t\t\t\t...\n\t\t\t\t\t<head name 1.M>.txt\n\t\t\t\t<head dir 1>.txt\n\t\t\t\t...\n\t\t\t\t<head dir N>.dir/\n\t\t\t\t\t<head name N.1>.txt\n\t\t\t\t\t...\n\t\t\t\t\t<head name N.P>.txt\n\t\t\t\t<head name 1>.txt\n\t\t\t\t...\n\t\t\t\t<head name Q>.txt\n\t\t\t...\n\t\t\ttags.dir/\n\t\t\t\t<tag name 1>.txt\n\t\t\t\t...\n\t\t\t\t<tag name T>.txt\n\t\t\t...\n\t...\n\tdescription -> annotations/description.txt\n\t...\n\n--\n"},{"id":"8201","messageId":"7vr7bzv3r2.fsf@assigned-by-dhcp.cox.net","threadId":"1736","inReplyTo":"432060B8.6080408@gmail.com","subject":"Re: [RFC] GIT Repository Annotation Convention","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2005-09-08T18:00:33Z","receivedAt":"2005-09-08T18:00:33Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"A Large Angry SCM <gitzilla@gmail.com> writes:\n\n> Naming and Directory Structure\n> ------------------------------\n> Annotations are named by appending \".txt\" to the basename of the\n> repository component it describes, and by appending \".dir\" to each\n> directory patch component leading to the repository component from\n> $GIT_DIR, and by prepending \"annotations/\" to the annotation pathname.\n\nI suspect you can do the same without .dir but only with .txt.\n"},{"id":"8204","messageId":"432083C2.6080704@gmail.com","threadId":"1736","inReplyTo":"43207B68.5020204@citi.umich.edu","subject":"Re: [RFC] GIT Repository Annotation Convention","fromName":"A Large Angry SCM","fromEmail":"gitzilla@gmail.com","sentAt":"2005-09-08T18:32:34Z","receivedAt":"2005-09-08T18:32:34Z","isPatch":false,"sender":{"key":"gitzilla@gmail.com","avatar":"https://gravatar.com/avatar/354625c442439908ff3dd99757dee330e29e9df7847472384faf7a00add247fb?d=mp&s=160"},"body":"Chuck Lever wrote:\n> yay!  are you also proposing some git tools to deal with these?  it \n> would be great to have some version control (keep these like generation \n> files so we can see the history of revisions).\n> \n> A Large Angry SCM wrote:\n>> GIT Repository Annotation Convention\n[...]\n\nI'm not proposing any new tools, just a convention that existing tools \nor tools that others may create can adopt to provide information to a \nrepositories users. Some existing tools that could use the annotations are:\n\tgit-branch\n\tgit-show-branch\n\tgitweb\nThere are likely others.\n\nLike any other file under $GIT_DIR, these files are not automatically \nversioned. Rather, each repository maintainer, needs to decide how a \nrepository's meta-data (project meta-meta-data) is tracked or generated.\n"},{"id":"8206","messageId":"432089D5.7000102@gmail.com","threadId":"1736","inReplyTo":"7vr7bzv3r2.fsf@assigned-by-dhcp.cox.net","subject":"Re: [RFC] GIT Repository Annotation Convention","fromName":"A Large Angry SCM","fromEmail":"gitzilla@gmail.com","sentAt":"2005-09-08T18:58:29Z","receivedAt":"2005-09-08T18:58:29Z","isPatch":false,"sender":{"key":"gitzilla@gmail.com","avatar":"https://gravatar.com/avatar/354625c442439908ff3dd99757dee330e29e9df7847472384faf7a00add247fb?d=mp&s=160"},"body":"Junio C Hamano wrote:\n> A Large Angry SCM <gitzilla@gmail.com> writes:\n> \n>>Naming and Directory Structure\n>>------------------------------\n>>Annotations are named by appending \".txt\" to the basename of the\n>>repository component it describes, and by appending \".dir\" to each\n>>directory patch component leading to the repository component from\n>>$GIT_DIR, and by prepending \"annotations/\" to the annotation pathname.\n> \n> I suspect you can do the same without .dir but only with .txt.\n\nThink about a directory containing directories \"foo\" and \"foo.txt\":\n\nWith \".dir\":\n\tfoo.dir/\n\t\t...\n\tfoo.txt\n\tfoo.txt.dir/\n\t\t...\n\tfoo.txt.txt\n\nWithout \".dir\":\n\tfoo/\n\t\t...\n==>\tfoo.txt\n==>\tfoo.txt/\n\t\t...\n\tfoo.txt.txt\n"},{"id":"8234","messageId":"43219B30.4040308@gmail.com","threadId":"1736","inReplyTo":"7vvf1bq64t.fsf@assigned-by-dhcp.cox.net","subject":"Re: [RFC] GIT Repository Annotation Convention","fromName":"A Large Angry SCM","fromEmail":"gitzilla@gmail.com","sentAt":"2005-09-09T14:24:48Z","receivedAt":"2005-09-09T14:24:48Z","isPatch":false,"sender":{"key":"gitzilla@gmail.com","avatar":"https://gravatar.com/avatar/354625c442439908ff3dd99757dee330e29e9df7847472384faf7a00add247fb?d=mp&s=160"},"body":"Junio C Hamano wrote:\n> A Large Angry SCM <gitzilla@gmail.com> writes:\n> \n>>Junio C Hamano wrote:\n>>>A Large Angry SCM <gitzilla@gmail.com> writes:\n>>>\n>>>>Naming and Directory Structure\n>>>>------------------------------\n>>>>Annotations are named by appending \".txt\" to the basename of the\n>>>>repository component it describes, and by appending \".dir\" to each\n>>>>directory patch component leading to the repository component from\n>>>>$GIT_DIR, and by prepending \"annotations/\" to the annotation pathname.\n>>>I suspect you can do the same without .dir but only with .txt.\n>>Think about a directory containing directories \"foo\" and \"foo.txt\":\n> \n> And where do you see foo.txt under $GIT_DIR/ hierarchy?\n\nAre you saying I can't name a branch \"foo.txt\"? Or have the following\nbranches?\n\n$GIT_DIR/refs/head/WidgetSoft/Blue\n$GIT_DIR/refs/head/WidgetSoft/Red\n$GIT_DIR/refs/head/WidgetSoft.txt/Blue\n$GIT_DIR/refs/head/WidgetSoft.txt/Red\n"},{"id":"8294","messageId":"pan.2005.09.11.16.37.20.483911@smurf.noris.de","threadId":"1736","inReplyTo":"432089D5.7000102@gmail.com","subject":"Re: [RFC] GIT Repository Annotation Convention","fromName":"Matthias Urlichs","fromEmail":"smurf@smurf.noris.de","sentAt":"2005-09-11T16:37:24Z","receivedAt":"2005-09-11T16:37:24Z","isPatch":false,"sender":{"key":"matthias@urlichs.de","avatar":"https://gravatar.com/avatar/2708905af227313eba6f2b2ae0f7d0259b5ac5d71baef58fe5a13c699ce0bbf0?d=mp&s=160"},"body":"Hi, A Large Angry SCM wrote:\n\n> Think about a directory containing directories \"foo\" and \"foo.txt\":\n> \nCan you tell us why you're using extensions in the first place?\n\nI propose using no extensions whatsoever: simply mirror the refs/ tree.\n\n-- \nMatthias Urlichs   |   {M:U} IT Design @ m-u-it.de   |  smurf@smurf.noris.de\nDisclaimer: The quote was selected randomly. Really. | http://smurf.noris.de\n - -\nThe rich get rich, and the poor get poorer.\nThe haves get more, the have-nots die.\n"},{"id":"8307","messageId":"43247298.2010500@gmail.com","threadId":"1736","inReplyTo":"pan.2005.09.11.16.37.20.483911@smurf.noris.de","subject":"Re: [RFC] GIT Repository Annotation Convention","fromName":"A Large Angry SCM","fromEmail":"gitzilla@gmail.com","sentAt":"2005-09-11T18:08:24Z","receivedAt":"2005-09-11T18:08:24Z","isPatch":false,"sender":{"key":"gitzilla@gmail.com","avatar":"https://gravatar.com/avatar/354625c442439908ff3dd99757dee330e29e9df7847472384faf7a00add247fb?d=mp&s=160"},"body":"Matthias Urlichs wrote:\n> Hi, A Large Angry SCM wrote:\n> \n>>Think about a directory containing directories \"foo\" and \"foo.txt\":\n>>\n> Can you tell us why you're using extensions in the first place?\n> \n> I propose using no extensions whatsoever: simply mirror the refs/ tree.\n> \n\nThe extensions allow the annotation of directories as well as files. \nThat's something that can't be done if extensions are not used.\n"},{"id":"8470","messageId":"pan.2005.09.13.17.45.59.307129@smurf.noris.de","threadId":"1736","inReplyTo":"43247298.2010500@gmail.com","subject":"Re: [RFC] GIT Repository Annotation Convention","fromName":"Matthias Urlichs","fromEmail":"smurf@smurf.noris.de","sentAt":"2005-09-13T17:46:00Z","receivedAt":"2005-09-13T17:46:00Z","isPatch":false,"sender":{"key":"matthias@urlichs.de","avatar":"https://gravatar.com/avatar/2708905af227313eba6f2b2ae0f7d0259b5ac5d71baef58fe5a13c699ce0bbf0?d=mp&s=160"},"body":"Hi, A Large Angry SCM wrote:\n\n>> I propose using no extensions whatsoever: simply mirror the refs/ tree.\n> \n> The extensions allow the annotation of directories as well as files. \n> That's something that can't be done if extensions are not used.\n\nIMHO, that is the sort of information that's best saved in the \"how is our\nsource organized\" section of your ./HACKING file.\n\nOr you can simply use reiserfs4, with its files-are-directories feature.\n(*ducks and runs*)\n\n-- \nMatthias Urlichs   |   {M:U} IT Design @ m-u-it.de   |  smurf@smurf.noris.de\nDisclaimer: The quote was selected randomly. Really. | http://smurf.noris.de\n - -\nAsk yourself whether you are happy and you cease to be so.\n"}]}