Improve tags

Improve tags

[Etienne Vallette d'Osia]

Hi,

I search a way to track commits in function of their aim.

I tried to use branches (test, debugger, etc).
For example if I search the commits related to tests,
I can search all commits what are in branch test and not in branch debugger,
but it's boring (I need to exclude all other branches than test)
Moreover, if I remove a branch, it will complicate the search.

In addition, branches are a way to specify streams,
not a way to specify an aim for a commit.
(like in ruby a class is a method container, not a type)
So branch names are often like next, pu, dev, test, stupid-idea, etc.
They are totally useless for tracking aims.

The method used in every repositories I looked into
is to use the "aim: subject" form in their commit messages.
So search all commits related to a specific aim is equivalent
to grep "my-aim:" in commit messages.
The problem is that this method is not used in all commits
("aim - subject" or just "subject" are used too),
so I can't assume to find all commits with a such method...
And if a search a more generic form ("test"), I might find
useless commits that will pollute my results...

The last method I can find, is to use tags.
But, as CVS and many others do, tags are unique.
It is usefull for tagging a software version number,
but not for tracking.

So, we have branches, which are not stable,
tags, which are unique,
and commit messages, which are not normalized.

What can we do ?

In my mind, the good ways are to improve the commit message way,
or, better, to change the current tag concept.

One improvement could be to add a mechanism similar to "signed-off-by:"
message: add an option in git-commit to facilitate the creation of "tags"
and make sure these "tags" will be normalized...
example: `git commit -t test,debugger -m "add test for debugger"`
         this will create a commit and add automatically
         "test: debugger:" at begin or
         "tags: test, debugger" at end of the message
           (like the "signed-off-by: xxx" lines)
It's not really better this current solution,
but it's a first step to normalization.

There is still a big problem with this solution : this tags are immutable,
as they are stored inside the commit.

An other improvement would be to create new version of tags.
`git tag v1.6.3` would create a unique tag, and
`git tag --no-unique test` would create a simple tag.
(until we can change the default)
The -t option of git-commit is still possible,
but it will call the new git-tag.

Note: Theses tags may be treated like refs (git log fault-tolerance),
but they can't be stored in $GIT_DIR/refs directory,
as they reference a list a commits...

So, I see 2 solutions:
- Normalize the way to write tags but keep them into commit message:
  (-) There will be 2 sorts of tags: static immutable and dynamic unique
  (+) This way is totally retro-compatible
- Change the tags concept:
  (-) Need to change the tag object format (ouch)
  (+) More powerful

Maybe I have missed a better tool to do my job ?
Or there is a better improvement which is more simple ?


Best regards,


Etienne Vallette d'Osia

ps: I'm really sorry if my message is full of English errors...

Re: Improve tags

[Michael J Gruber]

Etienne Vallette d'Osia venit, vidit, dixit 26.03.2009 13:48:
> Hi,
> 
> I search a way to track commits in function of their aim.
> 
> I tried to use branches (test, debugger, etc).
> For example if I search the commits related to tests,
> I can search all commits what are in branch test and not in branch debugger,
> but it's boring (I need to exclude all other branches than test)
> Moreover, if I remove a branch, it will complicate the search.
> 
> In addition, branches are a way to specify streams,
> not a way to specify an aim for a commit.
> (like in ruby a class is a method container, not a type)
> So branch names are often like next, pu, dev, test, stupid-idea, etc.
> They are totally useless for tracking aims.
> 
> The method used in every repositories I looked into
> is to use the "aim: subject" form in their commit messages.
> So search all commits related to a specific aim is equivalent
> to grep "my-aim:" in commit messages.
> The problem is that this method is not used in all commits
> ("aim - subject" or just "subject" are used too),
> so I can't assume to find all commits with a such method...
> And if a search a more generic form ("test"), I might find
> useless commits that will pollute my results...
> 
> The last method I can find, is to use tags.
> But, as CVS and many others do, tags are unique.
> It is usefull for tagging a software version number,
> but not for tracking.
> 
> So, we have branches, which are not stable,
> tags, which are unique,
> and commit messages, which are not normalized.
> 
> What can we do ?
> 
> In my mind, the good ways are to improve the commit message way,
> or, better, to change the current tag concept.
> 
> One improvement could be to add a mechanism similar to "signed-off-by:"
> message: add an option in git-commit to facilitate the creation of "tags"
> and make sure these "tags" will be normalized...
> example: `git commit -t test,debugger -m "add test for debugger"`
>          this will create a commit and add automatically
>          "test: debugger:" at begin or
>          "tags: test, debugger" at end of the message
>            (like the "signed-off-by: xxx" lines)
> It's not really better this current solution,
> but it's a first step to normalization.
> 
> There is still a big problem with this solution : this tags are immutable,
> as they are stored inside the commit.
> 
> An other improvement would be to create new version of tags.
> `git tag v1.6.3` would create a unique tag, and
> `git tag --no-unique test` would create a simple tag.
> (until we can change the default)
> The -t option of git-commit is still possible,
> but it will call the new git-tag.
> 
> Note: Theses tags may be treated like refs (git log fault-tolerance),
> but they can't be stored in $GIT_DIR/refs directory,
> as they reference a list a commits...
> 
> So, I see 2 solutions:
> - Normalize the way to write tags but keep them into commit message:
>   (-) There will be 2 sorts of tags: static immutable and dynamic unique
>   (+) This way is totally retro-compatible
> - Change the tags concept:
>   (-) Need to change the tag object format (ouch)
>   (+) More powerful
> 
> Maybe I have missed a better tool to do my job ?
> Or there is a better improvement which is more simple ?
> 
> 
> Best regards,
> 
> 
> Etienne Vallette d'Osia
> 
> ps: I'm really sorry if my message is full of English errors...

You described your motivation and use case very clearly!

Maybe "label" would be an appropriate name for "non-unique tags". I
assume they should be local and non-versioned. It sounds as if a file
storing a list of sha1s could be the simplest approach (one file per
label in a new subdir of .git), although this may not scale well. A
first step could be implementing a command "git label" in shell which
sets and displays labels. Later on, various builtins would need to be
taught about it if you want labels displayed in log etc.

Michael

Re: Improve tags

[Nanako Shiraishi]

Quoting "Etienne Vallette d'Osia" <dohzya@gmail.com>:

> In addition, branches are a way to specify streams,
> not a way to specify an aim for a commit.
> (like in ruby a class is a method container, not a type)
> So branch names are often like next, pu, dev, test, stupid-idea, etc.
> They are totally useless for tracking aims.

Why should that be?  'next' clearly states the aim (it is to serve as an
integration testing area for the possible new features for the next
release).

Quoting http://article.gmane.org/gmane.comp.version-control.git/113812

 (1) Name your (eh, "my") branch just like you name your function.

     You probably learned in programming 101 course the importance of
     giving a good name to your functions.  The same principle applies.
     When I see kb/checkout-optim branch, I know it is about optimizing
     the checkout command, and it came from Kjetil Barvik.  I can tell
     that jc/maint-1.6.0-read-tree-overlay is about the bugfix to the
     "overlay" feature of read-tree command, and the fix would apply as
     far back as the 1.6.0.X series, not just the current maintenance.


-- 
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/

Re: Improve tags

[Etienne Vallette d'Osia]

Nanako Shiraishi a écrit :
> Quoting "Etienne Vallette d'Osia" <dohzya@gmail.com>:
> 
>> In addition, branches are a way to specify streams,
>> not a way to specify an aim for a commit.
>> (like in ruby a class is a method container, not a type)
>> So branch names are often like next, pu, dev, test, stupid-idea, etc.
>> They are totally useless for tracking aims.
> 
> Why should that be?  'next' clearly states the aim (it is to serve as an
> integration testing area for the possible new features for the next
> release).
> 
It is not an aim (maybe "aim" is not the right term ?), it a status.
For me the aim is 'this commit is related to the documentation', 'this 
commit is related to test and to the debugger'.

Re: Improve tags

[Etienne Vallette d'Osia]

 > You described your motivation and use case very clearly!
 >
 > Maybe "label" would be an appropriate name for "non-unique tags". I
 > assume they should be local and non-versioned. It sounds as if a file
 > storing a list of sha1s could be the simplest approach (one file per
 > label in a new subdir of .git), although this may not scale well. A
 > first step could be implementing a command "git label" in shell which
 > sets and displays labels. Later on, various builtins would need to be
 > taught about it if you want labels displayed in log etc.
 >
 > Michael

Thanks a lot

"label" is perfect !

In fact, I was thinking about non-local labels.
But keeping information in a separate file and not in commit directly is 
a very nice idea (and closer than the current tag implementation).
I love your approach, you have just make this idea realizable

Re: Improve tags

[Jakub Narebski]

"Etienne Vallette d'Osia" <dohzya@gmail.com> writes:

>  > You described your motivation and use case very clearly!
>  >
>  > Maybe "label" would be an appropriate name for "non-unique tags". I
>  > assume they should be local and non-versioned. It sounds as if a file
>  > storing a list of sha1s could be the simplest approach (one file per
>  > label in a new subdir of .git), although this may not scale well. A
>  > first step could be implementing a command "git label" in shell which
>  > sets and displays labels. Later on, various builtins would need to be
>  > taught about it if you want labels displayed in log etc.
> 
> Thanks a lot
> 
> "label" is perfect !
> 
> In fact, I was thinking about non-local labels.
> But keeping information in a separate file and not in commit directly
> is a very nice idea (and closer than the current tag implementation).
> I love your approach, you have just make this idea realizable

This is a bit argument for (abandoned / dropped) 'notes' commit header
idea... But only a tiny bit.

More seriously: take a look at 'notes' idea; I'm not sure what state
they are currently, but they are in active (more or less) development.
They are extension of tags, allowing post-fact annotation of commits.

-- 
Jakub Narebski
Poland
ShadeHawk on #git

Re: Improve tags

[Etienne Vallette d'Osia]

on 27.03.2009 15:15, Jakub Narebski wrote:
 > More seriously: take a look at 'notes' idea; I'm not sure what state
 > they are currently, but they are in active (more or less) development.
 > They are extension of tags, allowing post-fact annotation of commits.
 >
git notes store a message related to _a specific_ commit.
It doesn't allow to find some commits.

In my mind, the best way to bind labels and notes (which would be great) 
is to allow to create a note related to a label.

Regards,

--
Etienne Vallette d'Osia