Re: Adding description within changed files

[Eric Siegerman]

On Mon, Sep 17, 2001 at 02:57:04PM +0200, Frank Thrum ( DAT TEC TI ) wrote:
> Christian Gudrian wrote:
> 
> > Right. But this sets the description [of what changed] right at the time of 
> > committing.
> > I would like to embed this description within the files itself using
> > special commands like $Id$ and such. I would comment my changes right
> > there where I do them: in the file. And I would then like CVS to read
> > through my files, extracting those comments and using them as
> > description.
> 
> Hallo,
> There is an RCS keyword "Log" which can help you.
> Include a line with
> 
>     $Log:$

$Log$ goes the other way, from commit message to file; he wants
to go from file to commit message.  But that's a quibble.

More importantly, $Log$ leads to *lots* of conflicts when you try
to merge two branches (trunk being equivalent to a branch for
this purpose).  You'll get a conflict on every file that was
changed on both branches, since the log's contents will be
different.  You'll have to merge the two logs yourself (and
either intersperse paragraphs from the different branches, making
it hard to follow, or live with the paragraphs being out of
chronological order).

(The same thing tends to happen with $Id$ too, but unlike $Log$
conflicts, it's trivial to repair -- just turn it back to a
simple "$Id$", or keep one or the other variant line at random,
and let the commit re-expand it.)

The other problem with $Log$ is that you now have the log message
stored in two places, one in the CVS metadata and one in the file
itself.  If someone later goes back and edits the log message in
either place, the change won't automatically be visible in the
other copy.  (And by having the log present in the files, there
will be a lot of temptation to go back and fix old messages.)

Much better to leave the $Log$ out and use "cvs log" to browse
the commit messsages.

--

|  | /\
|-_|/  >   Eric Siegerman, Toronto, Ont.        address@hidden
|  |  /
The world has been attacked.  The world must respond ... [but]
We must be guided by a commitment to do what works in the long run and
not by what makes us feel better in the short run.
        - Jean Chretien, Prime Minister of Canada
          on responses to the Sept. 11 terrorist attacks