comparison man/files.texi @ 42338:8649ccc72076

Rewrite Types of Log File node.

42337:aed4f1043eb8

replace SCCS, known as CSSC; if you are using SCCS and don't want to
make the incompatible change to RCS or CVS, you can switch to CSSC.

@menu
* Introduction to VC::  How version control works in general.
* VC Mode Line::     How the mode line shows version control status.
* Basic VC Editing::    How to edit a file under version control.
* Old Versions::        Examining and comparing old versions.
* Secondary VC Commands::    The commands used a little less frequently.
* Branches::            Multiple lines of development.
* Remote Repositories:: Efficient access to remote CVS servers.

check-in time.  However, CVS can also be set up to require locking.
(@pxref{CVS Options}).

@node Types of Log File
@subsubsection Types of Log File
@cindex Types of log file
@cindex Log File, types of 

GNU projects under a revision control system generally possess
@emph{two} types of log.  These help you keep track of what goes on.

One kind of log is the per-file log maintained by the revision control
system.  This kind of log is called the @dfn{version control log}, or
sometimes the @dfn{revision control log}, `@samp{*rcs*} log', or
`@samp{*cvs*} log'.  The other kind of log is a per-directory or
per-project log called the change log or @file{ChangeLog}.

@cindex Version control log
@cindex Revision control log
@cindex Per-file log
The per-file log is designed to tell you about each and every change
to a file.  Each time you check in a change, you fill out a version
control log entry.  (@xref{Log Buffer, Log Buffer, Features of the Log
Entry Buffer}.)  Consequently, a per-file log is very detailed, with
remarks such as `fixed typo' as well as `re-wrote from scratch'.

@cindex Change log
@cindex Per-directory log
@cindex Per-project log 
On the other hand, a per-directory or per-project log is intended to
provide a chronological record of when and why you and others changed
a program.  A @file{ChangeLog} should be moderately, but not
excessively detailed.

A single @file{ChangeLog} file can record changes for all
the files in its directory and all its subdirectories.  A small
program merits one @file{ChangeLog} file; a large program may well
merit several @file{ChangeLog} file, one in each major directory.
(@xref{Change Log, Change Log, Change Logs}.)

You can use the Emacs command @r{@kbd{C-x 4 a}}
(@code{add-change-log-entry-other-window}) to add a new entry to a
change log file.

If you use RCS or CVS, you can generate change log entries
automatically from the version control log entries using
the @r{@kbd{C-x v a}} (@code{vc-update-change-log}) command.
(@xref{Change Logs and VC, Change Logs and VC, Change Logs and VC}.)
When you do this, you will probably want to edit and shorten the
resulting @file{ChangeLog}.

@node VC Mode Line
@subsection Version Control and the Mode Line

  When you visit a file that is under version control, Emacs indicates

42338:8649ccc72076

replace SCCS, known as CSSC; if you are using SCCS and don't want to
make the incompatible change to RCS or CVS, you can switch to CSSC.

@menu
* Introduction to VC::  How version control works in general.
* VC Mode Line::        How the mode line shows version control status.
* Basic VC Editing::    How to edit a file under version control.
* Old Versions::        Examining and comparing old versions.
* Secondary VC Commands::    The commands used a little less frequently.
* Branches::            Multiple lines of development.
* Remote Repositories:: Efficient access to remote CVS servers.

check-in time.  However, CVS can also be set up to require locking.
(@pxref{CVS Options}).

@node Types of Log File
@subsubsection Types of Log File
@cindex types of log file
@cindex log File, types of 
@cindex version control log

GNU projects under a revision control system generally possess
@emph{two} types of log for changes.  One is the per-file log
maintained by the revision control system: each time you check in a
change, you must fill out a @dfn{log entry} for the change (@pxref{Log
Buffer}).  This kind of log is called the @dfn{version control log},
or sometimes the @dfn{revision control log}, `@samp{*rcs*} log', or
`@samp{*cvs*} log'.

The other kind of log the change log file, typically called
@file{ChangeLog}.  It provides a chronological record of all changes
to a large portion of a program---one directory and its
subdirectories.  A small program would use one @file{ChangeLog} file;
a large program may well merit a @file{ChangeLog} file in each major
directory.  @xref{Change Log}.

When you use version control, you can use just the per-file log if you
wish, or you can use both kinds of logs.  When you use both, you
typically want to write just one entry for each change.  You can write
the entry in @file{ChangeLog}, then copy it to the log buffer when you
check in the change.  Or you can write the entry in the log buffer
while checking in the change, and later use the @kbd{C-x v a} command
to copy it to @file{ChangeLog} (@pxref{Change Logs and VC}).

@node VC Mode Line
@subsection Version Control and the Mode Line

  When you visit a file that is under version control, Emacs indicates