Synopsis: history [OPTIONS] [FILENAME_SUBSTRING(S)]
- Alternate names – hi, his
- Requires – Repository, CVSROOT/history
- Changes – Nothing
Shows a history of activity in the repository. Specifically, this
option shows records of checkouts, commits, rtags, updates, and
releases. By default, the option shows checkouts (but see the -x
option). This command won't work if there's no CVSROOT/history file in
The history command differs from other CVS commands in several ways.
First, it must usually be given options to do anything useful (and some
of those options mean different things for history than they do
elsewhere in CVS). Second, instead of taking full file names as
arguments, it takes one or more substrings to match against file names
(all records matching at least one of those substrings are retrieved).
Third, history's output looks a lot like line noise until you learn to
read it, so I'll explain the output format in a special section, after
the options. (See also log.)
- -a – Shows history for all users (otherwise, defaults to self).
- -b STR – Shows data back to record containing string STR in the module
name, file name, or repository path.
- -c – Reports commits.
- -D DATE – Shows data since DATE (the usual CVS date formats are
- -e – Everything – reports on all record types.
- -f FILE – Reports the most recent event concerning FILE. You can
specify this option multiple times. This is different from the usual
meaning of -f in CVS commands: "Force to head revision as a last
- -l – Shows the record representing the last (as in "most recent") event
of each project. This is different from the usual meaning of -l in CVS
commands: "Run locally, do not recurse."
- -m MODULE – This provides a full report about MODULE (a project name).
You can specify this option multiple times.
- -n MODULE – Reports the most recent event about MODULE. For example,
checking out the module is about the module itself, but modifying or
updating a file inside the module is about that file, not about the
module. You can specify this option multiple times. This is different
from the usual meaning of -n in CVS commands: "Don't run a
- -o – Shows checkout records (the default).
- -p REPOS – Shows data for a particular directory in the repository.
You can specify this option multiple times. The meaning of this option
differs from the usual meaning of -p in CVS commands: "Pipe the data to
standard output instead of a file."
This option appears to be at least partially broken as of summer 1999.
- -r REV – Shows records referring to revisions since the revision or tag
named REV appears in individual RCS files. Each RCS file is searched
for the revision or tag.
- -T – Reports on all tag events.
- -t TAG – Shows records since tag TAG was last added to the history
file. This differs from the -r flag in that it reads only the
CVSROOT/history file, not the RCS files, and is therefore much faster.
- -u USER – Shows events associated with USER. You can specify this
option multiple times.
- -w – Shows records that are associated with the same working directory
from which you are invoking history.
- -X HISTORYFILE – Uses HISTORYFILE instead of CVSROOT/history. This
option is mainly for debugging and is not officially supported;
nevertheless, you may find it useful (perhaps for generating
human-readable reports from old history files you've kept around).
- -x TYPES – Reports on events specified in TYPES. Each type is
represented by a single letter, from the set `TOEFWUCGMAR'; any
number of letters can be combined. Here is what they mean:
- T – Tag
- O – Checkout
- E – Export
- F – Release
- W – Update (newly obsolete file removed from working copy)
- U – Update (file was checked out over user file)
- C – Update (merge, with conflicts)
- G – Update (merge, no conflicts)
- M – Commit (file was modified)
- A – Commit (file was added)
- R – Commit (file was removed)
The default, if no -x option is given, is to show checkouts (like
- -z ZONE – Displays times in output as for time zone ZONE. ZONE is an
abbreviated time zone name, such as UTC, GMT, BST, CDT, CCT, and so on.
A complete list of time zones is available in the TimezoneTable in the
file lib/getdate.c in the CVS source distribution.
The output of the history command is a series of lines; each line
represents one "history event" and starts with a single code letter
indicating what type of event it is. For example:
floss$ cvs history -D yesterday -x TMO
M 08/21 20:19 +0000 jrandom 2.2 baar myproj == <remote>
M 08/22 04:18 +0000 jrandom 1.2 README myproj == <remote>
O 08/22 05:15 +0000 jrandom myproj =myproj= ~/src/*
M 08/22 05:33 +0000 jrandom 2.18 README.txt myproj == ~/src/myproj
O 08/22 14:25 CDT jrandom myproj =myproj= ~/src/*
O 08/22 14:26 CDT jrandom [99.08.23.19.26.03] myproj =myproj= ~/src/*
O 08/22 14:28 CDT jrandom [Exotic_Greetings-branch] myproj =myproj= ~/src/*
The code letters are the same as for the -x option just described.
Following the code letter is the date of the event (expressed in UTC/GMT
time, unless the -z option is used), followed by the user responsible
for the event.
After the user might be a revision number, tag, or date, but only if
such is appropriate for the event (date or tag will be in square
brackets and formatted as shown in the preceding example). If you
commit a file, it shows the new revision number; if you check out with
-D or -r, the sticky date or tag is shown in square brackets. For a
plain checkout, nothing extra is shown.
Next comes the name of the file in question, or module name if the event
is about a module. If the former, the next two things are the
module/project name and the location of the working copy in the user's
home directory. If the latter, the next two things are the name of the
module's checked-out working copy (between two equal signs), followed by
its location in the user's home directory. (The name of the checked-out
working copy may differ from the module name if the -d flag is used with