thirdparty/vcs-load-dirs/docs/vcs_load_dirs.sgml

   1 <!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
   2   <!ENTITY vld "<application>vcs_load_dirs</application>">
   3 ]>
   4 <!--      "file:///usr/share/sgml/docbook/dtd/xml/4.2/docbookx.dtd"> -->
   5
   6 <reference>
   7   <title>vcs_load_dirs Manual</title>
   8
   9   <refentry>
  10     <refentryinfo>
  11       <address><email>jgoerzen@complete.org</email></address>
  12       <author><firstname>John</firstname><surname>Goerzen</surname></author>
  13     </refentryinfo>
  14
  15     <refmeta>
  16       <refentrytitle>vcs_load_dirs</refentrytitle>
  17       <manvolnum>1</manvolnum>
  18       <refmiscinfo>John Goerzen</refmiscinfo>
  19     </refmeta>
  20
  21     <refnamediv>
  22       <refname>vcs_load_dirs</refname>
  23       <refpurpose>Import upstream archives into tla, hg, darcs, or git and handle renames</refpurpose>
  24     </refnamediv>
  25
  26     <refsynopsisdiv>
  27       <cmdsynopsis>
  28         <command>vcs_load_dirs</command>
  29         <group>
  30           <arg>-w<replaceable>WC</replaceable></arg>
  31           <arg>--wc=<replaceable>WC</replaceable></arg>
  32         </group>
  33         <group>
  34           <arg>-l<replaceable>FILE</replaceable></arg>
  35           <arg>--log=<replaceable>FILE</replaceable></arg>
  36         </group>
  37         <group>
  38           <arg>-L<replaceable>TEXT</replaceable></arg>
  39           <arg>--log-message=<replaceable>TEXT</replaceable></arg>
  40         </group>
  41         <group>
  42           <arg>-s<replaceable>MSG</replaceable></arg>
  43           <arg>--summary=<replaceable>MSG</replaceable></arg>
  44         </group>
  45         <group>
  46           <arg>-v</arg>
  47           <arg>--verbose</arg>
  48         </group>
  49         <group>
  50           <arg>-n</arg>
  51           <arg>--no-commit</arg>
  52         </group>
  53         <group>
  54           <arg>-f</arg>
  55           <arg>--fs-changes-only</arg>
  56         </group>
  57         <arg choice="plain">vendor_source_dir</arg>
  58       </cmdsynopsis>
  59
  60       <cmdsynopsis>
  61         <command>vcs_load_dirs</command>
  62         <arg choice="plain">--version</arg>
  63       </cmdsynopsis>
  64
  65       <cmdsynopsis>
  66         <command>vcs_load_dirs</command>
  67         <group>
  68           <arg choice="plain">--help</arg>
  69           <arg choice="plain">-h</arg>
  70         </group>
  71       </cmdsynopsis>
  72
  73     </refsynopsisdiv>
  74
  75     <refsect1>
  76       <title>Description</title>
  77       <para>
  78         &vld; is a tool to help you import archives from people that
  79         do not use Arch, Mercurial, Darcs, or Git into an Arch,
  80         Mercurial, Darcs, or Git
  81         archive.  Along the way, it takes
  82         care of all the typical hassles: it will create tags in the
  83         repository for new files; delete tags for removed files;
  84         and move tags for files that have themselves been moved.
  85         &vld; can handle both first imports of a package and
  86         successive imports.
  87       </para>
  88       <para>
  89         For those familiar with Subversion, you will know that it has
  90         a tool called <application>svn_load_dirs</application>.  &vld;
  91         is modeled after that program, but contains various
  92         improvements for ease of use.
  93       </para>
  94     </refsect1>
  95
  96     <refsect1>
  97       <title>Usage</title>
  98       <para>
  99         In the simplest case, you will simply run &vld; from your
 100         working directory, passing it the name of the directory
 101         containing the new upstream sources.  &vld will run, usually
 102         making and commiting changes without any need of greater
 103         assistance from you.
 104       </para>
 105       <refsect2>
 106         <title>Renamed Files</title>
 107         <para>
 108           &vld; can automatically detect added files and deleted files
 109           if they occur in isolation.  However, it cannot
 110           automatically tell the difference between a delete and an
 111           add, and a rename.  (There is not enough information in
 112           simple upstream imports to capture the intent.)
 113           Therefore, &vld; will prompt you to solve the problem.
 114           You can opt to ignore it -- &vld; will just issue deletes
 115           and adds as appropriate -- but then your history will be
 116           harder to track if there were indeed renames along the way.
 117         </para>
 118         <para>
 119           You will be presented with a four-column listing.  Those
 120           columns, in order from left to right, represent:
 121         </para>
 122         <orderedlist>
 123           <listitem><para>File number for deleted file</para>
 124           </listitem>
 125           <listitem><para>File name of deleted file</para>
 126           </listitem>
 127           <listitem><para>File number of added file</para>
 128           </listitem>
 129           <listitem><para>File name of added file</para>
 130           </listitem>
 131         </orderedlist>
 132         <para>
 133           You have three options at this point: you can press q to
 134           indicate that there are no more renames; you can press r to
 135           request the list be re-drawn, or you can supply one or more
 136           renames.
 137         </para>
 138         <para>
 139           A rename uses the left column as the old name and the right
 140           column as the new name.  To save you typing, you just enter
 141           the appropriate file numbers separated by spaces.  So, if
 142           the file at position 5 on the left moved to position 1b on
 143           the right, just enter "5 1b".  After doing that, the list
 144           will be automatically re-drawn, and you can either make
 145           further selections or exit.
 146         </para>
 147         <para>
 148           If you want to rename several files at once, enter your
 149           rename commands separated by commas.  For instance, "5 1b, 6
 150           1c".
 151         </para>
 152       </refsect2>
 153     </refsect1>
 154
 155     <refsect1>
 156       <title>Options</title>
 157
 158       <variablelist>
 159         <varlistentry><term>-h</term>
 160           <term>--help</term>
 161           <listitem><para>Displays a brief summary of the available
 162               options and exits.</para>
 163           </listitem>
 164         </varlistentry>
 165
 166         <varlistentry><term>-l<replaceable>FILE</replaceable></term>
 167           <term>--log=<replaceable>FILE</replaceable></term>
 168           <listitem><para>
 169               Add the contents of <replaceable>FILE</replaceable> to
 170               the end of the log message automatically generated by
 171               &vld; for a commit/record.
 172             </para>
 173           </listitem>
 174         </varlistentry>
 175
 176         <varlistentry><term>-L<replaceable>TEXT</replaceable></term>
 177           <term>--log-message=<replaceable>TEXT</replaceable></term>
 178           <listitem><para>
 179               Add the <replaceable>TEXT</replaceable> specified on the
 180               command line to the log message.
 181             </para>
 182           </listitem>
 183         </varlistentry>
 184
 185         <varlistentry><term>-s<replaceable>MSG</replaceable></term>
 186           <term>--summary=<replaceable>MSG</replaceable></term>
 187           <listitem>
 188             <para>
 189               Sets the log summary line to the
 190               <replaceable>MSG</replaceable> supplied on the command
 191               line.  This operation requires Darcs, Mercurial, or
 192               tla 1.1 or above; tla 1.0
 193               does not provide the features necessary to implement it.
 194             </para>
 195           </listitem>
 196         </varlistentry>
 197
 198         <varlistentry><term>-n</term>
 199           <term>--no-commit</term>
 200           <listitem><para>
 201               Do not commit changes to the target VCS.
 202             </para>
 203           </listitem>
 204         </varlistentry>
 205
 206         <varlistentry><term>-f</term>
 207           <term>--fs-changes-only</term>
 208           <listitem><para>
 209               Move files in the filesystem, but do not inform VCS of
 210               changes.  You will almost certainly want to use this
 211               with -n.  This also suppresses the interactive interface.
 212             </para>
 213           </listitem>
 214         </varlistentry>
 215
 216         <varlistentry><term>-v</term>
 217           <term>--verbose</term>
 218           <listitem><para>Causes &vld; to display additional status
 219               information.  You will see the darcs/tla/git/hg commands that are
 220               being run behind the scenes, and some executed commands
 221               may receive arguments asking them to be more verbose as
 222               well.
 223             </para>
 224           </listitem>
 225         </varlistentry>
 226
 227         <varlistentry><term>--version</term>
 228           <listitem><para>Causes &vld; to print its version number and
 229               exit.
 230             </para>
 231           </listitem>
 232         </varlistentry>
 233
 234         <varlistentry><term>-w<replaceable>WC</replaceable></term>
 235           <term>--wc=<replaceable>WC</replaceable></term>
 236           <listitem>
 237             <para>
 238               Explicitly set the working copy directory to
 239               <replaceable>WC</replaceable>.  If not specified,
 240               defaults to the current working directory.
 241             </para>
 242           </listitem>
 243         </varlistentry>
 244       </variablelist>
 245     </refsect1>
 246     <refsect1>
 247       <title>Copyright</title>
 248       <para>&vld;, and this manual, are Copyright &copy; 2003-2007 John Goerzen.</para>
 249
 250       <para>
 251         This program is free software; you can redistribute it and/or modify
 252         it under the terms of the GNU General Public License as published by
 253         the Free Software Foundation; either version 2 of the License, or
 254         (at your option) any later version.
 255       </para>
 256
 257       <para>
 258         This program is distributed in the hope that it will be useful,
 259         but WITHOUT ANY WARRANTY; without even the implied warranty of
 260         MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 261         GNU General Public License for more details.
 262       </para>
 263
 264       <para>
 265         You should have received a copy of the GNU General Public License
 266         along with this program; if not, write to the Free Software
 267         Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA</para>
 268
 269     </refsect1>
 270
 271     <refsect1>
 272       <title>Author</title>
 273       <para>&vld;, its libraries, documentation, and all included files, except where
 274         noted, was written by John Goerzen <email>jgoerzen@complete.org</email> and
 275         copyright is held as stated in the COPYRIGHT section.
 276       </para>
 277
 278       <para>
 279         The homepage for &vld; is
 280         <ulink
 281         url="http://software.complete.org/vcs-load-dirs"></ulink>
 282       </para>
 283       <para>
 284         This package may be downloaded from
 285         <ulink
 286           url="http://packages.debian.org/vcs-load-dirs"></ulink>.
 287         darcs users may also obtain the latest version with:
 288         <screen>
 289 $ darcs get --partial http://darcs.complete.org/vcs-load-dirs
 290         </screen>
 291       </para>
 292     </refsect1>
 293
 294     <refsect1>
 295       <title>See Also</title>
 296       <para>
 297         <application>tla</application>(1),
 298         <application>darcs</application>(1),
 299         <application>hg</application>(1),
 300         <application>git</application>(1),
 301         <application>tla-buildpackage</application>(1),
 302         <application>darcs-buildpackage</application>(1),
 303         <application>hg-buildpackage</application>(1).
 304       </para>
 305     </refsect1>
 306   </refentry>
 307 </reference>
 308
 309 <!--
 310 Local Variables:
 311 mode: sgml
 312 sgml-set-face: T
 313 End:
 314 -->