hist

show the transaction history of elements or an entire depot

Usage

accurev hist [ -t <transaction-range> ] [ -s <stream> ] [ -c <comment> ]
[ -u <users> [ --exclude_users ] ]
[ -k <transaction-kinds> [ --exclude_kinds ] ]
[ -f <format(s)> ] [ --show_historic_cpk ]
{ -a | <element-list> | [ -Fx ] -l <list-file> | -e <eid> }
[ -p <depot-name> ] [ -R ]

Description

Note: As an alternative to “hist”, you can use the command-name “history”.

The hist command displays part or all of the transaction history of one or more elements. For each transaction, it reports the creation time, who made changes, comments for each version, etc. For each version involved in a transaction, it reports the virtual version, the real version, the transaction number, the transaction time, who created the version and how, and the comment.

Options

-a

Operate on all elements in the depot. You can use this option instead of specifying a list of elements.

-c <comment-string>

Display only transaction(s) whose comments contain the specified string. (The string matching is case-insensitive.) Enclose the string in quotes to ensure that hist interprets it as a single command-line argument.

-e <eid>

Operate on the element with the specified element-ID. If you also specify a <list-file> or <element-list>, it is ignored.

-p <depot-name>

By default, AccuRev uses the depot of the current workspace as its context. Use this option to specify a different depot, or to specify a depot when there is no current workspace.

-R

Recurse into each directory element specified and continue to show transaction history within. The -R option requires at least one element or the -l option. The -R option cannot be used with the -a option.

-s <stream>

Display only the transactions that involved the specified stream. If you use this option, you must specify elements using depot-relative pathnames or element-IDs (-e option).

-f<format(s)>

Use one or more of the following format letters or numbers:

-3: ("third-party") For issue numbers associated with a version, display the third-party ITS key and value for the issue.
-e: (“expanded”) Display more detail for promote transactions: information on the transaction(s) in the current workspace (keep, move, etc.) that recorded the change(s) being promoted.
-i: ("issue") Display issues related to a version of an element at the time of the specified transaction. If a version is not currently the head of an issue, but was at the time of the transaction, the issue is displayed with an attribute historic_only=true. This attribute is not displayed if the version is currently the head and was also the head at the time of the transaction.
-v: (“verbose”) For keep and add transactions, include the modification time, checksum, file size, data type (text or binary), and depot-relative pathname. cpk transactions are listed as add or remove, followed by details of the cpk add or cpk remove operation.
(You can use -fev to display both expanded and verbose information.)
-l: (“list”) For each transaction, show only the path of the element. For move transactions, only the destination is shown.
-s: (“status”) If the displayed version of the element is in the default group of the stream specified with -s (default: workspace stream), list it with “(member)”. This option is intended to be used in combination with -t, when you’re examining a transaction listed by translist.
-t: (“transaction”) Display just the header line, including the transaction number.
-c: (“csv”) Display header information as comma-separated values. The output includes comments provided at Keep or Promote time. Note: This option is valid only in conjunction with the -t format option.
-x: (“XML”) Display results in XML format.

-Fx

Signals that <list-file> (see the -l option) is an XML-format file, not a flat text file. Example:

	<transactions>
    <id>1</id>
    <id>6</id>
</transactions>

-l <list-file>

Process the elements listed in <list-file>. This must be a text file, with one element name per line. Extra whitespace is not allowed; make sure there are no empty lines and no leading or trailing white space around the filenames. Wildcards are not expanded. There is no provision for comment lines in the file.

If you use this option, any <element-list> specified is silently ignored.

<element-list>

One or more element names, separated by whitespace. If you also specify a <list-file> using the –l option, this <element-list> is silently ignored.

-k <transaction-kinds>

Display only the transactions of the specified kind(s). Valid values are:
add, archive, chstream, co, defcomp, defunct,
demote_from, demote_to, dispatch, eacl, keep, move,
mkstream, promote, purge, unarchive, undefunct
(removed-hidden: stream)

You may specify multiple types using the -k option by separating the types with commas.

Note: When you use -k defcomp, AccuRev returns transactions of the following types, all of which are related to setting include/exclude rules:

incl, excl, incldo, and clear

If there are no transactions of these types associated with the element, AccuRev returns:

No history corresponding to selection.

Note that you cannot use -k to filter these transaction types directly.

--exclude_kinds

Use in conjunction with the -k option to indicate that the output should display all kinds of transactions except for the named kind(s).

-u <users>

Display only the transactions for the specified AccuRev user(s).

You may specify multiple users using the -u option by separating the usernames with commas. If any of the names contains a space, place double quotes around the entire list of names.

--exclude_users

Use in conjunction with the -u option to indicate that the output should display transactions executed by all users except for the named user(s).

--show_historic_cpk[=true]

Display the state of the related change package as it was at the time of the specified transaction. By default, the current state of the change package is shown. The "=true" argument is optional and explicitly specifying it is the same as omitting it. Providing any other string than "true" is the same as omitting --show_historic_cpk altogether and will result in the current state of the change package being displayed.

-t <time-spec>[ .<count> ]

--

-t <time-spec> - <time-spec>[ .<count> ]

The first form specifies one transaction, or a specified number of transactions up to (i.e. preceding) and including a particular transaction.

The second form specifies transactions that took place in the specified interval; the optional suffix truncates the listing after the most recent <count> transactions. You may need to use quotes in composing the argument following -t; the entire argument must be interpreted by the command shell as a single token. The command output depends on the order of the time-specs; list the most recent time-spec first to show the results in order from most recent to least recent. Reverse the order of the time-specs to reverse the order of the output.

A time-spec can be any of the following:

  • Time in <"YYYY/MM/DD HH:MM:SS"> format, "2007/08/07 20:27:15", for example. Note that you must use quotes when specifying time-spec as YYYY/MM/DD HH:MM:SS to ensure that the entire argument is interpreted by the command shell as a single token.
  • Time keyword: now
  • Transaction number as a positive integer: e.g. 146 or 23965
  • Transaction number keyword: highest

When using the –t option, take into account the possibility of a timewarp. The AC_SYNC environment variable (see AccuRev User Preferences) determines how a timewarp will be handled. See also System Clock Synchronization in the AccuRev Admin Guide.

Specifying the Transactions

By default, hist displays the entire transaction history of the element(s), or of the entire depot. The various forms of the -t option restrict the display to a single transaction, or to a range of transactions. Each variant involves one or two time-specs. A single time-spec means “the transaction that took place at this time” or “the most recent transaction that took place before this time”. Two time-specs define an interval; hist reports all the transactions in the interval that involve the element(s) you’ve specified.

Examples

Display the transaction history for each element in the current directory:

> accurev hist *

Display the transactions involving the current directory itself:

> accurev hist .

Display transactions 145 through 176, inclusive:

> accurev hist -t "176-145"

Display the five most recent transactions, with a verbose listing of keep and create transactions:

> accurev hist -t now.5 -fv

Display header lines for the five most recent transactions, in csv format:

> accurev hist -t now.5 -ftc

Display all the transactions for element base.cc that involved stream gizmo_test:

> accurev hist -s gizmo_test base.cc

Display all the transactions for element base.cc that were executed by users other than john smith and jones:

> accurev hist -u "john smith,jones" --exclude_users base.cc

Display information on the most recent promote transaction, including the keep transactions that preceded it:

   > accurev hist -t now -k promote -fe
transaction 113; promote; 2007/02/19 17:55:55 ; user: john
\.\src\brick.h 13/2 (16/2)

# add RIVER
version 16/2 (16/2)
ancestor: (16/1)

# remove ALLOCSIZE
version 16/1 (16/1)
ancestor: (15/1)

Note that the output of this command can be in XML format if you specify -fex instead of -fe at the command line. The <streams> element details all the dynamic streams and workspace streams involved in the reported transaction(s). A transaction’s timestamp (time attribute of the XML element <transaction>) is reported as the number of seconds since Jan. 1, 1970 UTC. Special Field Types describes a technique for converting this timestamp into a human-readable string.

Note: If you have been parsing the XML output from the hist command, you will need to check that you are getting the correct <stream> tag, since that tag now appears within both the <transaction> and the <streams> tags. The content of the new <stream> tag will vary depending on the AccuRev command recorded in the transaction.

Display issues related to a version of an element at the time of promote transactions, and format the output in XML. Note the <historic_only> tag at the end, indicating that the version is no longer the head, but was at the time of the transaction.

> accurev hist -fix -a -k promote

<AcResponse
     Command="hist"
     TaskId="1032">

....

<transaction
       id="11"
       type="promote"
       time=""
       user="testuser1">
    <version
         path="\.\file_0003"
         eid="4"
         virtual="2/2"
         real="4/2"
         virtualNamedVersion="s22245/2"
         realNamedVersion="ws22245_1_testuser1/2"
         elem_type="text"
         dir="no">
       <issueNum>2</issueNum>
    </version>
</transaction>
<transaction
       id="9"
       type="promote"
       time=""
       user="testuser1">
    <version
         path="\.\file_0003"
         eid="4"
         virtual="2/1"
         real="4/1"
         virtualNamedVersion="s22245/1"
         realNamedVersion="ws22245_1_testuser1/1"
         elem_type="text"
         dir="no">
       <issueNum
         historic_only="true">2</issueNum>
    </version>
</transaction>

Display all AccuWork ("dispatch") transactions in XML format, using verbose mode. Note that any cpk add and cpk remove transactions are flagged in the XML output with cpk= attributes in the <transaction> tag.

> accurev hist -fvx -a -k dispatch
<AcResponse
    Command="hist"
    TaskId="1036">
  <transaction
       id="16"
       type="dispatch"
       time=""
       user="testuser1"
       cpk="add">
     <issues>
       <issue>
           <issueNum>3</issueNum>
           <elements>
               <element
                   eid="2"
                   member="1"
                   head_version="4/2"
                   basis_version="0/0"
                   name="/file_0001"/>
           </elements>
       </issue>
     </issues>
     <streams>
       <stream
           id="4"
           name="ws22245_1_testuser1"
           type="workspace"/>
     </streams>
  </transaction>
  <transaction
       id="15"
       type="dispatch"
       time=""
       user="testuser1"
       cpk="remove">
     <issues>
       <issue>
           <issueNum>3</issueNum>
           <elements>
               <element
                   eid="2"
                   member="0"
                   name="/file_0001"/>
           </elements>
       </issue>
     </issues>
  </transaction>

 

Display in the xml output the state of the change package related to transaction #2123 as it was at the time of the transaction:

   > accurev hist --show_historic_cpk -t 2123 -fx

See Also

translist

Techniques for Selecting Elements