<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

<refentry>
  <refentryinfo>
    <date>2002-04-29</date>
  </refentryinfo>

  <refmeta>
    <refentrytitle>prcsstatus</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>prcsstatus</refname>
    <refpurpose>What's in my tree?</>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>prcsstatus</>
      <arg opt><option>-w</option></arg>
      <arg opt><option>-P</option></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Options</title>

    <variablelist>
      <varlistentry>
	<term><option>-w</></term>
	<listitem>
	  <para>append unknown files to .ignore in each directory</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>-P</></term>
	<listitem>
	  <para>don't consider project control files</para>
	</listitem>
      </varlistentry>
    </variablelist>

  <refsect1>
    <title>Description</title>

    <para><literal>prcsstatus</> walks from the current directory upwards
    stopping when it finds one or more files which end in .prj (PRCS
    project control files).  This directory is known as the
    <emphasis>project root</>.</para>

    <para>For each of the .prj files in the project root, it gathers a list
    of the files in that project, warning if a file is present in more than
    one project.  It then gets PRCS to generate 3 sets of diffs: working vs
    common, selected vs common, and selected vs working.  It stashes the
    results of these diffs for later use.</para>

    <para><literal>prcsstatus</> then walks down the directory tree from
    the point where it was initially started, printing a one-line summary
    of the state each interesting file is in.  A file is interesting if it
    has been changed somewhere, either in your tree or in the PRCS
    repository.</para>

    <para>The possible states a file might be in are as follows:</para>

    <variablelist>
      <varlistentry>
	<term><emphasis role=bold>? : unknown</></term>
	<listitem>
	  <para>A file is unknown if it is not mentioned in any project in
	  the project root.  These files might be newly create source files
	  which should be <literal>prcs populate</>-ed or might simply be
	  junk files.  You can list files to be ignored by listing them in
	  a <filename>.ignore</> file in the same directory.  These
	  <filename>.ignore</> files can be automatically generated by
	  invoking <literal>prcsstatus</> with the <option>-w</> flag; this
	  is useful immediately after the first compile when all the
	  generated files have been created but no changes have yet been
	  made.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
        <term><emphasis role=bold>M : modified</></term>
	<listitem>
	  <para>A file is modified if you've edited the copy locally, and
	  no-one else has checked a newer version into the
	  repository.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><emphasis role=bold>U : updated version in repository</></term>
	<listitem>
	  <para>A file needs updating if someone has checked in a new
	  version to the repository, and you haven't edited your copy.  A
	  straightforward <literal>prcs merge</> should fix this.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
	<term><emphasis role=bold>3 : 3-way conflict</></term>
	<listitem>
	  <para>A file has a 3-way conflict if it has been edited locally,
	  and the local copy is no longer the latest, and the originally
	  checked out version is not the latest.  This is quite a complex
	  condition, and it can arise in one of three ways:</para>

	  <variablelist>
	    <varlistentry>
	      <term><emphasis role=bold>same as M:</></term>
	      <listitem>
		<para>you've done a merge, then subsequently edited the file;
		  or</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><emphasis role=bold>same as U:</></term>
	      <listitem>
		<para>you've done a merge, then someone else checked in;
		  or</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><emphasis role=bold>real conflict:</></term>
	      <listitem>
		<para>you've done a merge, edited the file, then someone
		  else has checked in.
		</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>

	  <para>Unfortunately, <literal>prcsstatus</> is unable to tell
	  these three cases apart: they all look alike.  This is the major
	  weakness of <literal>prcsstatus</>.  The real problem is that
	  PRCS makes it hard to to tell the result of a merge apart from
	  your own edits: both look like the file has been edited
	  locally.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><emphasis role=bold>O : only in ...</></term>
	<listitem>
	  <para>One of the 3 diffs said the file only existed in one of the
	  versions.  This could be because the file has been deleted in the
	  repository, or because this is a new file that has been
	  <literal>prcs populate</>-ed but not yet committed.  Again, this
	  is an area in which <literal>prcsstatus</> could be improved to
	  detect which of these distinct scenarios is actually the case.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Historical Note</title>

    <para>I wrote the <literal>prcsstatus</> tool because I'd used <ulink
    url="http://www.sourcegear.com/CVS">cvs</> before and liked the way I
    could type</para>

    <programlisting>
      cvs -n update
    </programlisting>

    <para>to get a concise listing of what I'd changed in my working
    tree.</para>

    <para>Then we started using <ulink url="http://prcs.sourceforge.net/">
    PRCS</> at work, and I found it impossible to work out what was in my
    tree.</para>

    <para>Furthermore, the way we use PRCS is to have multiple projects
    checked out on top of each other, such that each file in the working
    tree is <quote>owned</> by one PRCS project.  Dealing with this was the
    final straw that broke the camel's back: I needed something to tell me
    the status of each file in my tree, and which PRCS project was
    responsible for it.  Thus was born <literal>prcsstatus</>.</para>
  </refsect1>


  <refsect1>
    <title>Bug reports</title>

    <para>Please mail bug reports, etc, to Austin Donnelly
    <email>Austin_Donnelly@yahoo.co.uk</>.  Patches to fix bugs or add
    features most welcome!</para>
  </refsect1>

  <refsect1>
    <title>Authors</title>

    <para>Austin Donnelly <email>Austin_Donnelly@yahoo.co.uk</></para>

    <para>This manual page was translated to DocBook by Rafael Laboissiere
    <email>rafael@debian.org</>.</para>

  </refsect1>
</refentry>
