The hated $Log$ keyword

[Richard Wesley]

Hi all -

I am talking to some folks (both in house and at another company) 
about $Log$ functionality, and I have some questions that I was 
hoping someone could answer quickly:

- Is there a more detailed discussion of the problems than what 
appears at ?
- Is there any way to specify the format of the comments without 
editing the server?
- Who does the insertion anyway, the client or the server?

BTW, I appreciate the arguments against using $Log$ (redundancy, 
merging, admin -m, etc.), but these guys really like the Header 
Comments functionality they had with another system (MPW Projector) 
so I'm trying to figure out what will work best for everyone.  At 
least they aren't bitching about concurrency ;-)

TIA,

- rmgw

http://www.electricfish.com/hawkfish/


Richard Wesley   Electric Fish, Inc.   [EMAIL PROTECTED]

"No, no no.  'Eureka' is Greek:  It means 'This bath is too hot.'"
  - Dr. Who, _The Talons of Wen Chi-Ang_

___
Info-cvs mailing list
[EMAIL PROTECTED]
http://mail.gnu.org/mailman/listinfo/info-cvs

Re: The hated $Log$ keyword

[Greg A. Woods]

[ On Wednesday, May 2, 2001 at 10:39:47 (-0700), Richard Wesley wrote: ]
> Subject: The hated $Log$ keyword
>
> BTW, I appreciate the arguments against using $Log$ (redundancy, 
> merging, admin -m, etc.), but these guys really like the Header 

Teach them to use "cvs log" (and even "cvs rlog" now).

Either that or teach them to use GNU-style "ChangeLog" files (which is
really trivial with some tools)

You could also use "rcs2log" as part of your release process too,
depending on exactly when/where such log files are desired.

There is no way to "fix" $Log.  It is broken by design.

-- 
Greg A. Woods

+1 416 218-0098  VE3TCP  <[EMAIL PROTECTED]> <[EMAIL PROTECTED]>
Planix, Inc. <[EMAIL PROTECTED]>;   Secrets of the Weird <[EMAIL PROTECTED]>

___
Info-cvs mailing list
[EMAIL PROTECTED]
http://mail.gnu.org/mailman/listinfo/info-cvs

Re: The hated $Log$ keyword

[Todd Denniston]

"Greg A. Woods" wrote:
> 
> [ On Wednesday, May 2, 2001 at 10:39:47 (-0700), Richard Wesley wrote: ]
> > Subject: The hated $Log$ keyword
> >
> > BTW, I appreciate the arguments against using $Log$ (redundancy,
> > merging, admin -m, etc.), but these guys really like the Header
> 
> Teach them to use "cvs log" (and even "cvs rlog" now).
> 
> Either that or teach them to use GNU-style "ChangeLog" files (which is
> really trivial with some tools)

I have found that cvs2cl.pl also does a really nice job of generating the logs
I need (and I used to like $Log$ when we used rcs), it even tries to generate
the 'GNU-style "ChangeLog" files' Greg is talking about.  When you run it
against the whole of the repository it lets you see more easily how changes
relate to the different files, or if you want the history of just one or a few
files you can specify them on the command line.
take a look at it here:
http://www.red-bean.com/cvs2cl/

-- 
__
Todd Denniston, Code 6067, NSWC Crane mailto:[EMAIL PROTECTED]
I'd crawl over an acre of 'Visual This++' and 'Integrated Development
That' to get to gcc, Emacs, and gdb.  Thank you.
-- Vance Petree, Virginia Power

___
Info-cvs mailing list
[EMAIL PROTECTED]
http://mail.gnu.org/mailman/listinfo/info-cvs

Re: The hated $Log$ keyword

[Martin Neitzel]

>BTW, I appreciate the arguments against using $Log$ (redundancy, 
>merging, admin -m, etc.), but these guys really like the Header 
>Comments functionality they had with another system (MPW Projector) 

Back in the 80's when I was starting with rcs I considered $Log$
entries to be cute at first.  I soon found out that the entries
have these handicaps:

- At rev 1.20, the old entries tend to turn into superfluous ballast
  rather than useful information (perhaps a bit like the GPL in every
  file ;-)

- Like $Header$ information, it brings its own kind of troubles to
  diffs/patches.

- The Cederquist already points out in the place referenced by you
  that spelling and other fixes in the $Log$ area are a big no-no.
  Nevertheless, the temptation to do so is high, and it is difficult
  just to accept any deficiences in this area.

I stopped using $Log$ info in the files with rcs and never did
so with cvs.  "Hidden logs" are just fine since you can always
get them back with "cvs log" (or rcs' "rlog").  The Number One
selling point for hidden logs is (in my opinion) that you
can get a concise summary of the recent changes by "cvs log -D ...".
Nobody wants to grope through the $Log$ entries in *all* source
files in order to get such a summary.  I tell my team partners
about "cvs log -D ..." because it's necessary to quickly identify
the possibles causes for a wrecked system.   Internal $Log$s
wouldn't be a substitute for a "cvs log ..." across the entire
project.

HTH, Martin Neitzel

___
Info-cvs mailing list
[EMAIL PROTECTED]
http://mail.gnu.org/mailman/listinfo/info-cvs

Re: The hated $Log$ keyword

[James Youngman]

Richard Wesley <[EMAIL PROTECTED]> writes:

> BTW, I appreciate the arguments against using $Log$ (redundancy, 
> merging, admin -m, etc.), but these guys really like the Header 
> Comments functionality they had with another system (MPW Projector) 
> so I'm trying to figure out what will work best for everyone.  At 
> least they aren't bitching about concurrency ;-)


I also get bitten by $Log$ when merging, but OTOH I still use it.
This is partly because some of the projects I work on use "cvs export"
to affiliated projects whose only access to log information is
readeing the expanded log (though, yes, ChangeLog would be as good for
this).   

What if there was a keyword like $Log$ but which expanded to the
entire log history (with comment leaders)?   This would avoid the
merge problem and surely cannot be too expensive to compute.
Thoughts?

-- 
James Youngman
Manchester, UK.  +44 161 226 7339
PGP (GPG) key ID for <[EMAIL PROTECTED]> is 64A95EE5 (F1B83152).

___
Info-cvs mailing list
[EMAIL PROTECTED]
http://mail.gnu.org/mailman/listinfo/info-cvs

Re: The hated $Log$ keyword

[Greg A. Woods]

[ On , July 7, 2001 at 18:22:09 (+0100), James Youngman wrote: ]
> Subject: Re: The hated $Log$ keyword
>
> What if there was a keyword like $Log$ but which expanded to the
> entire log history (with comment leaders)?   This would avoid the
> merge problem and surely cannot be too expensive to compute.
> Thoughts?

Why not just add "cvs log" to the release process??

You can even use "rcs2log" to get ChangeLog-style files.

Using "cvs log" (or "cvs rlog") avoids all these silly problems related
to $Log once and for all!

If absolutely necessary I'm sure it wouldn't take any competent
programmer more than an hour or two to come up with a script that would
walk over the tree resulting from "cvs export -kv" and insert all of the
per-file log history into a comment at the top/bottom/middle of every
file.

RCS keywords are evilly implemented at best, and $Header, $Log, and a
few similar are just totally evil from the get go.  Avoid them like the
plague.

-- 
Greg A. Woods

+1 416 218-0098  VE3TCP  <[EMAIL PROTECTED]> <[EMAIL PROTECTED]>
Planix, Inc. <[EMAIL PROTECTED]>;   Secrets of the Weird <[EMAIL PROTECTED]>

___
Info-cvs mailing list
[EMAIL PROTECTED]
http://mail.gnu.org/mailman/listinfo/info-cvs

Re: The hated $Log$ keyword

[Eric Siegerman]

On , July 7, 2001 at 18:22:09 (+0100), James Youngman wrote:
> Subject: Re: The hated $Log$ keyword
>
> What if there was a keyword like $Log$ but which expanded to the
> entire log history (with comment leaders)?   This would avoid the
> merge problem and surely cannot be too expensive to compute.

It would indeed avoid the merge problem (or at least reduce it)
... but it's *impossible* to compute in the presence of branches.
CVS doesn't keep around enough info to know which revisions of
which branches actually contributed to the rev in question.
(That's a problem that wants solving for other reasons, of
course, as has been discussed in the past.)

On Sat, Jul 07, 2001 at 05:49:30PM -0400, Greg A. Woods wrote:
> RCS keywords are evilly implemented at best, and $Header, $Log, and a
> few similar are just totally evil from the get go.  Avoid them like the
> plague.

I thoroughly agree about $Log$, but:
  - what's evil about the rest?
  - why do you put $Header$ in the "totally evil" class, not
merely evil?

--

|  | /\
|-_|/  >   Eric Siegerman, Toronto, Ont.[EMAIL PROTECTED]
|  |  /
With sufficient thrust, pigs fly just fine. However, this is not
necessarily a good idea.
- RFC 1925 (quoting an unnamed source)

___
Info-cvs mailing list
[EMAIL PROTECTED]
http://mail.gnu.org/mailman/listinfo/info-cvs

Re: The hated $Log$ keyword

[Greg A. Woods]

[ On Sunday, July 8, 2001 at 20:13:40 (-0400), Eric Siegerman wrote: ]
> Subject: Re: The hated $Log$ keyword
>
> I thoroughly agree about $Log$, but:
>   - what's evil about the rest?

The "evil" thing abou RCS keyword design is that they contain their
values when stored in the ,v file, and that they contain their markers
when they appear in a "frozen" file.

This was one of the several things that hindsight shows us SCCS did
right in the first place, especially when you're using it as an
underlying tool for delta management in something like CVS.

>   - why do you put $Header$ in the "totally evil" class, not
> merely evil?

$Header contains information that has no business ever being seen in the
file content, especially in CVS, though even in plain RCS use it is
bogus.  If you move your repo all that info becomes wrong even though
nothing else has to break.

Well over a decade ago I argued for something half-way between $Id and
$Header in RCS, and I repeated that plea when CVS-II first appeared.
What I wanted was a way to expand just the relative path-prefix within
the repository.  It would have been doable in RCS without much problem,
and with CVS it's actually trivial (though I think CVS still contains an
implementation bug that would make it harder than it should be, and of
course CVS modules attempt to be way more than anyone ever needs,
further complicating the issue).  As it is I usually end up hard-coding
the module name and relative path within the module into my ident strings.

-- 
Greg A. Woods

+1 416 218-0098  VE3TCP  <[EMAIL PROTECTED]> <[EMAIL PROTECTED]>
Planix, Inc. <[EMAIL PROTECTED]>;   Secrets of the Weird <[EMAIL PROTECTED]>

___
Info-cvs mailing list
[EMAIL PROTECTED]
http://mail.gnu.org/mailman/listinfo/info-cvs

Re: The hated $Log$ keyword

[Eric Siegerman]

On Sun, Jul 08, 2001 at 10:39:52PM -0400, Greg A. Woods wrote:
> The "evil" thing abou RCS keyword design is that they contain their
> values when stored in the ,v file,

Mmm, yes.  If it stripped out the values at commit time, and just
stored the keywords, all these *#(! merge conflicts would go
away.


> and that they contain their markers
> when they appear in a "frozen" file.

Why is this a problem?  I very much prefer it.  Suppose, using
SCCS or raw RCS, I accidentally edit a file I haven't locked.
With RCS, once I've seen the "permission denied" message, I can:
  :!co -l foo
  :w!

The SCCS equivalent would inappropriately freeze all my keywords.

OK, that's a really dumb thing to do when collaborating with
others.  But then, I've rarely collaborated using raw RCS, and
never with SCCS; by the time I had coworkers who were willing to
consider version control at all, I'd discovered CVS :-)

> This was one of the several things that hindsight shows us SCCS did
> right in the first place, especially when you're using it as an
> underlying tool for delta management in something like CVS.

I don't see how one could even do CVS-style unreserved checkouts
layered on top of something which handled its keywords the way
SCCS does.  Should a checkout give you the values (in which case,
the magic-keyword-ness is lost on commit), or the keywords (in
which case, why bother with keywords in the first place since
they never get substituted)?

I'm trying to think of how one could get this to work.  You'd
have to do some kludge like:
  - check out with values only into the user's sandbox (actually,
SCCS itself gives you no choice, if I recall, since the only
way to get keywords only is "get -e", which also acquires a
lock)

  - at commit time, do a merge between:
  1. a fresh checkout with values only
  2. another fresh checkout with keywords only
  3. the sandbox file
i.e. diff (1) and (2) and apply the results to (3) as a patch

Shudder!  Every commit becomes a merge; it happens at commit
time, not update time, so the user can't inspect the results; a
conflict is guaranteed if the user so much as touches the
keyword-values or their immediate vicinity; two revision
checkouts per commit.  Have I listed all the problems yet?
Likely not...


> 
> >   - why do you put $Header$ in the "totally evil" class, not
> > merely evil?
> 
> $Header contains information that has no business ever being seen in the
> file content, especially in CVS, though even in plain RCS use it is
> bogus.  If you move your repo all that info becomes wrong even though
> nothing else has to break.

Point taken.

> Well over a decade ago I argued for [...]
> a way to expand just the relative path-prefix within
> the repository

Now that you mention it, I seem to recall wishing for the same
thing (not quite a decade ago), but never got around to griping
about it.  Maybe I should have :-)

--

|  | /\
|-_|/  >   Eric Siegerman, Toronto, Ont.[EMAIL PROTECTED]
|  |  /
With sufficient thrust, pigs fly just fine. However, this is not
necessarily a good idea.
- RFC 1925 (quoting an unnamed source)

___
Info-cvs mailing list
[EMAIL PROTECTED]
http://mail.gnu.org/mailman/listinfo/info-cvs

Re: The hated $Log$ keyword

[Greg A. Woods]

[ On Monday, July 9, 2001 at 00:01:01 (-0400), Eric Siegerman wrote: ]
> Subject: Re: The hated $Log$ keyword
>
> > and that they contain their markers
> > when they appear in a "frozen" file.
> 
> Why is this a problem?  I very much prefer it.  Suppose, using
> SCCS or raw RCS, I accidentally edit a file I haven't locked.
> With RCS, once I've seen the "permission denied" message, I can:
>   :!co -l foo
>   :w!
> 
> The SCCS equivalent would inappropriately freeze all my keywords.
> 
> OK, that's a really dumb thing to do when collaborating with
> others.  But then, I've rarely collaborated using raw RCS, and
> never with SCCS; by the time I had coworkers who were willing to
> consider version control at all, I'd discovered CVS :-)

Well, with CVS the meaning of "frozen" file is quite a bit different.

In the most basic sense what I'm saying is that "-kv" should be the
default for "cvs export".

In a pure RCS environment the issue with keyword markers in unlocked
files is somewhat more complex.  If I'm not mis-remembering the history
of this feature part of the original intent was to allow for exactly the
scenario you describe above.  Another "feature" of this ability was to
allow a new RCS ,v file to be created with initial defaults for various
values, such as the revision number (i.e. with "ci -k"):

 This option is useful for
  software  distribution.  A revision that is sent to
  several sites should be  checked  in  with  the  -k
  option at these sites to preserve the original num-
  ber, date, author, and state.

In practice I don't think this scheme has ever worked very well unless
all sites in question had an agreed upon branching plan since you still
have to either reserve branch numbers for each site (or invent some tool
to do branch renumbering, which is I think what BitKeeper does).

Of course in both CVS and RCS the ultimate problem with having the
keyword markers in the frozen files is that subsequent checkins/imports
to a new repository (without '-k') will clobber the old value.  This is
why '-kv' should be the default for "cvs export", and why large projects
using RCS (or those using CVS who haven't learned to use "cvs export")
have always invented their own project-specific keyword (eg. $NetBSD,
$Xconsortium, $XFree86, etc.)

(Which reminds me -- someone with commit access really should commit the
patches from OpenBSD that implement "tag=OpenBSD" in CVSROOT/config!)

BTW, with plain SCCS the "workaround" for saving changes to unlocked
files is to save only the diff and apply it again to the locked file:

sccs diff foo.c > foo.diff
rm foo.c
sccs edit foo.c
patch foo.c < foo.diff  # no patch? use 'diff -e' and 'ed' 
sccs delget foo.c

> I don't see how one could even do CVS-style unreserved checkouts
> layered on top of something which handled its keywords the way
> SCCS does.  Should a checkout give you the values (in which case,
> the magic-keyword-ness is lost on commit), or the keywords (in
> which case, why bother with keywords in the first place since
> they never get substituted)?

In order to follow the SCCS style of keyword handling CVS would have to
always provide only the un-expanded keywords in working directories
(i.e. use "co -kk" in the case of RCS, or always create the working
directory with "get -k" in the case of SCCS).  At least this was the
conclusion I came to when I was trying to figure out how to make CVS
work as an SCCS front-end.

Yes this would significantly reduce the utility of keywords, at least
for the way many people use them today.

However in many environments such a scheme would be more or less
invisble (eg. in emacs with the VC hooks enabled the checked out
revision is given in the mode line).

One advantage of such a scheme would be that people who wanted to use
keywords to tag all their published files would soon learn when and how
to use "cvs export" and they'd be much less likely to accidentally
publish something from within a working directory!  ;-)

> I'm trying to think of how one could get this to work.  You'd
> have to do some kludge like:
>   - check out with values only into the user's sandbox (actually,
> SCCS itself gives you no choice, if I recall, since the only
> way to get keywords only is "get -e", which also acquires a
> lock)

No need to do the lock with SCCS, just use "get -k"

>   - at commit time, do a merge between:
>   1. a fresh checkout with values only
>   2. another fresh checkout with keywords only
> 

Re: The hated $Log$ keyword

[Eric Siegerman]

On Mon, Jul 09, 2001 at 04:12:30AM -0400, Greg A. Woods wrote:
> [ On Monday, July 9, 2001 at 00:01:01 (-0400), Eric Siegerman wrote: ]
> Well, with CVS the meaning of "frozen" file is quite a bit different.
> 
> In the most basic sense what I'm saying is that "-kv" should be the
> default for "cvs export".

Ah, now I get it.  Agreed -- except that it shouldn't override
"-kb" of course.

>  This option is useful for
>   software  distribution.  A revision that is sent to
>   several sites should be  checked  in  with  the  -k
>   option at these sites to preserve the original num-
>   ber, date, author, and state.
> 
> In practice I don't think this scheme has ever worked very well unless
> all sites in question had an agreed upon branching plan 

Or even if there was only one site.  I tried this with a couple
of open-source things I downloaded, and quickly ran into the
problem of new files going in at 1.1 instead of 5.1 or whatever.
Same problem that makes "cvs ci -r2" not very useful.

> Of course in both CVS and RCS the ultimate problem with having the
> keyword markers in the frozen files is that subsequent checkins/imports
> to a new repository (without '-k') will clobber the old value.  This is
> why '-kv' should be the default for "cvs export", and why large projects
> using RCS (or those using CVS who haven't learned to use "cvs export")
> have always invented their own project-specific keyword (eg. $NetBSD,
> $Xconsortium, $XFree86, etc.)

One way to solve this would be to make the vendor branch a
special case.  When checking out a file (whether with "co" or
"update"), if you're getting it from the vendor branch, override
the file's keyword-substitution setting and just do "-ko".

So when I import the CVS sources (for e.g.) and do a fresh
checkout, my sandbox will contain the original $Id$ values that
were in the distribution.  When I modify and commit some file,
*only* that file will now contain $Id$ values of the revision
from my repo.

(Ideally -kb should trump this wrinkle, as it should all other
check-out-time -k settings, but that's another story.)

--

|  | /\
|-_|/  >   Eric Siegerman, Toronto, Ont.[EMAIL PROTECTED]
|  |  /
With sufficient thrust, pigs fly just fine. However, this is not
necessarily a good idea.
- RFC 1925 (quoting an unnamed source)

___
Info-cvs mailing list
[EMAIL PROTECTED]
http://mail.gnu.org/mailman/listinfo/info-cvs

Re: The hated $Log$ keyword

[Greg A. Woods]

[ On Wednesday, July 11, 2001 at 15:40:04 (-0400), Eric Siegerman wrote: ]
> Subject: Re: The hated $Log$ keyword
>
> On Mon, Jul 09, 2001 at 04:12:30AM -0400, Greg A. Woods wrote:
> > 
> > In the most basic sense what I'm saying is that "-kv" should be the
> > default for "cvs export".
> 
> Ah, now I get it.  Agreed -- except that it shouldn't override
> "-kb" of course.

If you believe '-kb' should even exist, of course!  ;-)

> One way to solve this would be to make the vendor branch a
> special case.  When checking out a file (whether with "co" or
> "update"), if you're getting it from the vendor branch, override
> the file's keyword-substitution setting and just do "-ko".

Yes, that's another good idea -- and it's probably even been mentioned
in this forum within the last half decade or so!  ;-)

-- 
Greg A. Woods

+1 416 218-0098  VE3TCP  <[EMAIL PROTECTED]> <[EMAIL PROTECTED]>
Planix, Inc. <[EMAIL PROTECTED]>;   Secrets of the Weird <[EMAIL PROTECTED]>

___
Info-cvs mailing list
[EMAIL PROTECTED]
http://mail.gnu.org/mailman/listinfo/info-cvs