update @version in file

update @version in file

[takeshin]

Hi,

I have following PHPDoc code in files of my repository:

/**
 * Class description
 * @version 1.2
 */
 class Name…

Is there a chance that git could increment this @version automatically
on each commit or stamp the file somehow?

I'm using git on Windows.

-- 
regards
takeshin


-- 
View this message in context: http://n2.nabble.com/update-%40version-in-file-tp2879913p2879913.html
Sent from the git mailing list archive at Nabble.com.

Re: update @version in file

[Andreas Ericsson]

takeshin wrote:
> Hi,
> 
> I have following PHPDoc code in files of my repository:
> 
> /**
>  * Class description
>  * @version 1.2
>  */
>  class Name…
> 
> Is there a chance that git could increment this @version automatically
> on each commit

No, but see GIT-VERSION-GEN and "git help describe" for info on how to
replace such version tags using a script when you cut a release of your
project.

> or stamp the file somehow?
> 

Yes. It can only do so using the blob id though. Things like this can
be done in CVS and Subversion because
a) CVS and SVN are file-based. The version they write are not the
   version of the *project*, but the version of the file (not even
   remotely the same thing).
b) they do not really support proper branching.

In git (which is snapshot based and supports branching very well indeed),
it *could* be done, but it would incur such an enormous performance
penalty when switching branches, creating a new commit or re-writing
history (since every file would have to be altered) that it's never
been considered worth adding.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

Register now for Nordic Meet on Nagios, June 3-4 in Stockholm
 http://nordicmeetonnagios.op5.org/

Considering the successes of the wars on alcohol, poverty, drugs and
terror, I think we should give some serious thought to declaring war
on peace.

Re: update @version in file

[takeshin]

Thank you for such a quick and comprehensive answer.

-- 
regards
takeshin


-- 
View this message in context: http://n2.nabble.com/update-%40version-in-file-tp2879913p2880239.html
Sent from the git mailing list archive at Nabble.com.

Re: update @version in file

[Jakub Narebski]

Andreas Ericsson <ae@op5.se> writes:
> takeshin wrote:

> > Hi,
> > I have following PHPDoc code in files of my repository:
> > /**
> >  * Class description
> >  * @version 1.2
> >  */
> >  class Name…
> > Is there a chance that git could increment this @version
> > automatically
> > on each commit
> 
> No, but see GIT-VERSION-GEN and "git help describe" for info on how to
> replace such version tags using a script when you cut a release of your
> project.
> 
> > or stamp the file somehow?
> >
> 
> Yes. It can only do so using the blob id though. 

See documentation of `ident` attribute in gitattributes(5) manpage.

Well, you can always use `export-subst` gitattribute to make
git-archive do keyword expansion, and there you can use things like
date or decoration (tag / version).

> Things like this can be done in CVS and Subversion because
> a) CVS and SVN are file-based. The version they write are not the
>    version of the *project*, but the version of the file (not even
>    remotely the same thing).
> b) they do not really support proper branching.
> 
> In git (which is snapshot based and supports branching very well indeed),
> it *could* be done, but it would incur such an enormous performance
> penalty when switching branches, creating a new commit or re-writing
> history (since every file would have to be altered) that it's never
> been considered worth adding.

You can cobble something together using "smudge" (to do keyword
expansion) and "clean" (to store files with keywords not expanded in
git repository) filters, see `filter` attribute in gitattributes(5).
But I am not sure it is worth it.

HTH
-- 
Jakub Narebski
Poland
ShadeHawk on #git

Re: update @version in file

[Dan Loewenherz]

On 13/05/09 02:42 -0700, Jakub Narebski wrote:
> Andreas Ericsson <ae@op5.se> writes:
> > No, but see GIT-VERSION-GEN and "git help describe" for info on how to
> > replace such version tags using a script when you cut a release of your
> > project.

Couldn't Git be a little more friendly? 

You can choose to ignore an uncommitted file through the `git update-index 
--assume-unchanged` command. But AFAIK, Git doesn't allow one to ignore 
uncommitted _lines_ in tracked files. If this feature were implemented, a 
post commit hook could write in the latest commit hash and git wouldn't care.

Is this something that is worth pursuing?

      Dan

Re: update @version in file

[Jakub Narebski]

On Wed, 13 May 2009, Dan Loewenherz wrote:
> On 13/05/09 02:42 -0700, Jakub Narebski wrote:
> > Andreas Ericsson <ae@op5.se> writes:

> > > No, but see GIT-VERSION-GEN and "git help describe" for info on how to
> > > replace such version tags using a script when you cut a release of your
> > > project.
> 
> Couldn't Git be a little more friendly? 

No, Git cannot have that feature.

> You can choose to ignore an uncommitted file through the `git update-index 
> --assume-unchanged` command. But AFAIK, Git doesn't allow one to ignore 
> uncommitted _lines_ in tracked files. If this feature were implemented, a 
> post commit hook could write in the latest commit hash and git wouldn't care.

No, I am afraid it is not possible. Let me explain

1. Git doesn't touch files which didn't change during rewinding (going
   back in history, perhaps to start development of maintenance branch,
   or doing bisection of history to find commit which introduced a bug),
   and when switching branches. If keyword expansion was about *commit*
   information (like description/decoration e.g. 'v1.6.3-17-g35805ce',
   or author, or change date) then when switching branches (going to
   other commit, with other info) you would have to rewrite all files.
   This would very badly affect performance. Also, when committing you
   would have to rewrite all files.

2. If you wanted however to have *file* version (like in CVS), then it
   is impossible because Git doesn't store such info (well, beside
   blob id of a contents of a file, but that is not exactly a version
   number); moreover it doesn't make much sense to know such number.
   It is next to useless; it is changesets that matter. CVS has it
   because it evolved from file-based version control system, only
   cobbled together.
 
> Is this something that is worth pursuing?

You can write your own clear/smudge filters if you are stubborn
about having version info in files which are under version control
(and you can ask SCM at which version you are), rather than adding
version info on release (so the program can support --version option).
-- 
Jakub Narebski
Poland

Re: update @version in file

[Matthieu Moy]

Jakub Narebski <jnareb@gmail.com> writes:

> 2. If you wanted however to have *file* version (like in CVS), then it
>    is impossible because Git doesn't store such info

What could make sense is the commit id where the file was last
modified (i.e. the first item that appears when one runs "git log" on
the file). Not exactly as simple as it could be because of merge, but
not completely meaningless either.

-- 
Matthieu

Re: update @version in file

[Andreas Ericsson]

Matthieu Moy wrote:
> Jakub Narebski <jnareb@gmail.com> writes:
> 
>> 2. If you wanted however to have *file* version (like in CVS), then it
>>    is impossible because Git doesn't store such info
> 
> What could make sense is the commit id where the file was last
> modified (i.e. the first item that appears when one runs "git log" on
> the file). Not exactly as simple as it could be because of merge, but
> not completely meaningless either.
> 

That would also incur an impossible performance penalty. A *LOT* of
projects have a LICENSE file that hasn't been changed since the project
was put under version control in the first place. Is git suppose to
dig through history for every revision just to make sure that the
LICENSE file hasn't been changed since 1999?

Now think about such a feature for a project with 20k+ files (not even
very large, as projects go) and see how much time you lose when
switching branches. Then ask yourself: What's more important: Developer
time or version numbers in files that can be hacked in to match the
entire project's version when releasing?

100% of all discussions about this on git@vger has ended up with the
conclusion that it's not worth wasting a couple of seconds of a
developer's time for this feature to exist. That's why this feature
doesn't exist in git yet.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

Register now for Nordic Meet on Nagios, June 3-4 in Stockholm
 http://nordicmeetonnagios.op5.org/

Considering the successes of the wars on alcohol, poverty, drugs and
terror, I think we should give some serious thought to declaring war
on peace.

Re: update @version in file

[Jakub Narebski]

On Wed, 13 May 2009, Matthieu Moy napisał:
> Jakub Narebski <jnareb@gmail.com> writes:
> 
> > 2. If you wanted however to have *file* version (like in CVS), then it
> >    is impossible because Git doesn't store such info
> 
> What could make sense is the commit id where the file was last
> modified (i.e. the first item that appears when one runs "git log" on
> the file). Not exactly as simple as it could be because of merge, but
> not completely meaningless either.

First, while it quite neatly solves the problem of cost of commit (only
changed files needs to have keyword expansion updated), it is also much
more costly (possibly much, much more, especially as Andreas wrote for
files which change rarely) than commit info based keywords (like those
`export-subst` keywords).  Note that Git doesn't store per-file version
info.

Second, you are mistaken thinking that 'commit id where the file was
last modified' is a file-level variable.  It is not, because file could
have arrived independently at given contents (e.g. by cherry-picking
bugfix, or by reverting some change one one branch while other is from
before a change).  See for example sample history below


   .---.---.---a--.---b---.---c     <--- branch_1
                \
                 \--.---d---c'      <--- branch_2

where given file is at the same version (has the same contents) in both
"c" and "c'" commits, but for one 'last changed' would be "b", for other
it would be "d".

This means that not only rewinding is costly (as per previous point), but
also switching branches is costly; you have to get history for each and
every file, even if they didn't change in the switch.

Third, files in project are not independent. Last commit the file was
changed doesn't give us much informational value, I don't think. Well,
at least not as keyword expansion; you might want to ask your SCM about
this info.  Whole project tags means that you can get to exact version
you stated.  "File history" revision numbers would not.


I don't know why you need such keyword. Users either browse files via SCM
(where they have access to SCM to get such info, or browse files from
tarball, where project revision is embedded (substituted by Makefile)...

-- 
Jakub Narebski
Poland

Re: update @version in file

[Matthieu Moy]

Jakub Narebski <jnareb@gmail.com> writes:

> I don't know why you need such keyword.

Hey, don't get me wrong: I didn't say I needed it, but just that it
wasn't completely meaningless. No intention to flame, sorry ;-).

-- 
Matthieu