repomapper.xml 5.27 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE refentry PUBLIC
   "-//OASIS//DTD DocBook XML V4.1.2//EN"
   "docbook/docbookx.dtd">
<refentry id='repomapper.1'>
<refmeta>
<refentrytitle>repomapper</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class='date'>Aug 26 2015</refmiscinfo>
<refmiscinfo class='productname'>repomapper</refmiscinfo>
<refmiscinfo class='source'>repomapper</refmiscinfo>
<refmiscinfo class='manual'>Development Tools</refmiscinfo>
</refmeta>
<refnamediv id='name'>
<refname>repomapper</refname>
16
<refpurpose>update and manipulate contributor maps</refpurpose>
17 18 19 20 21
</refnamediv>
<refsynopsisdiv id='synopsis'>

<cmdsynopsis>
  <command>repomapper</command>
22
      <arg choice="opt">-i</arg>
23
      <arg choice="opt">-p <replaceable>passwordfile</replaceable></arg>
24
      <arg choice="opt">-u <replaceable>updatefile</replaceable></arg>
25 26
      <arg choice="opt">-h <replaceable>host</replaceable></arg>
      <arg choice='plain'><replaceable>contribmap</replaceable></arg>
27 28 29 30 31 32
</cmdsynopsis>
</refsynopsisdiv>

<refsect1 id='description'><title>DESCRIPTION</title>

<para>Older, centralized version-control systems such as CVS and
33
SVN centralize a repository on one host and identify users by their
34 35 36 37 38 39 40
account names on that host.  Distributed version-control systems such
as git and Mercurial identify users by a netwide-unique ID consisting
of a name-among-humans followed by an email address.</para>

<para>When moving a repository from a centralized to a distributed
system, therefore, one of the prerequisites is a contributor map that
associates each account name on the old system to a DVCS-style ID
41
on the new one.  This tool automates parts of that process.</para>
42

43 44
<para>The main argument file must be a contributor map such as is read
by the <command>authors read</command> subcommand of
45 46 47
<citerefentry><refentrytitle>reposurgeon</refentrytitle><manvolnum>1</manvolnum></citerefentry>. It
may be a fresh or stub map, produced by <command>authors
write</command> before any human-name or email information has been
48 49
added to the repository.  Or it may have name-among-humans and email
information filled in for some entries.</para>
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64

<para>A stub map entry looks something like this:

<programlisting>
foonly = foonly &lt;foonly&gt;
</programlisting>
</para>

<para>The same entry, fully filled in, might look something like this:

<programlisting>
foonly = Fred Foonly &lt;foonly@fubar.net&gt;
</programlisting>
</para>

65 66 67 68 69 70 71
<para>The default behavior of the tool is to report all map entries,
in effect a sorting copy of the file.</para>

<para>With -i, it reports only entries that are not yet in DVCS form -
that is, either the fullname field on the right side of the equals
sign is identical to the account name on the left, or the email field
contains no @-sign, or both.</para>
72 73

<para>With the -p option, this tool fills in the full-name field using
74 75 76 77 78 79 80 81 82
the password file given as the option's argument. Only the username
and the comment (or 'gecos') field containing the user's
name-among-humans are used. Other fields are ignored, including the
password-hash field.  (On modern Unixes this field does not contain
the actual hash, which lives in a different file named
<filename>/etc/shadow</filename>, so <filename>/etc/passwd</filename>
can be shared without security risk.)</para>

<para>In the -p mode, for each entry in the contrib file the program
83 84
looks for a username in the password file matching the name to the
left of the equal sign.  If a match is found, the user's
85 86
name-among-humans is extracted from the gecos field and replaces the
text between the <quote>=</quote> and the <quote>&lt;</quote>.</para>
87 88 89 90 91 92 93 94 95 96 97 98 99 100 101

<para>Thus, the stub line above and the
<filename>/etc/passwd</filename> line

<programlisting>
foonly:x:1000:1000:Fred Foonly,,,:/home/foonly:/bin/bash
</programlisting>

will combine to produce this on output:

<programlisting>
foonly = Fred Foonly &lt;foonly&gt;
</programlisting>

Note that the email-address part (and, if present, the
102 103 104 105
optional trailing timezone field) are not normally modified.</para>

<para>However, if the -h option is given, the argument is taken to be
a host name which should be appended (after a @) to every email field
106
that does not already contain a @.  The argument would typically be the
107
fully-qualified domain name of the repository host.</para>
108

109 110 111 112
<para>Thus, if the passwd file still contains an entry for every
committer (which might not be the case if inactive committer accounts
were ever removed), -p mode combined with an -h option can produce
an entire, valid contributor map.</para>
113

114 115 116 117 118 119 120
<para>In the -u mode of operation, the option argument must be a
second contributor file, which is taken as a source of updates.  Each
contributor entry with a username not matching any in the first
contributor map is copied into the first map, which is output.</para>

<para>Output from this tool is always a contrib map sorted by
username.</para>
121 122 123 124 125 126 127 128 129 130 131 132 133 134 135
</refsect1>

<refsect1 id='see_also'><title>SEE ALSO</title>

<para><citerefentry><refentrytitle>reposurgeon</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>

</refsect1>

<refsect1 id='author'><title>AUTHOR</title>

<para>Eric S. Raymond <email>esr@thyrsus.com</email>. This tool is
distributed with reposurgeon; see the project page at <ulink
url='http://www.catb.org/~esr/reposurgeon'>http://www.catb.org/~esr/reposurgeon</ulink>.</para>
</refsect1>
</refentry>