Rename authors -> _authors in VCSBackend.authors() loop to avoid clobber.
[update-copyright.git] / README
1 ``update-copyright`` is an automatic copyright updating tool.  I wrote
2 the original for `Bugs Everywhere`_, but ended up copying it into a
3 number of my projects.  Copying is bad, so here it is, split out as
4 its own separate project.
5
6 Installation
7 ============
8
9 Packages
10 --------
11
12 Gentoo
13 ~~~~~~
14
15 I've packaged ``update-copyright`` for Gentoo_.  You need layman_ and
16 my `wtk overlay`_.  Install with::
17
18   # emerge -av app-portage/layman
19   # layman --add wtk
20   # emerge -av dev-util/update-copyright
21
22 Dependencies
23 ------------
24
25 ``update-copyright`` is a simple package with few external
26 dependencies.  The only external dependencies are the Python packages
27 behind Python-based version control systems.  If you're using those
28 VCSs, you've already installed the packages.  If you're not using
29 those VCSs, you don't need the packages.
30
31 Installing by hand
32 ------------------
33
34 ``update-copyright`` is available as a Git_ repository::
35
36   $ git clone git://tremily.us/update-copyright.git
37
38 See the homepage_ for details.  To install the checkout, run the
39 standard::
40
41     $ python setup.py install
42
43 Usage
44 =====
45
46 You'll need a project that you version with one of our supported VCSs
47 (currently Git, Mercurial, and Bazaar, but it should be pretty easy to
48 add backends for other systems).  You'll also need a config file
49 called ``.update-copyright.conf`` in your package root, which will be
50 parsed using Python's RawConfigParser_ (`syntax documentation`_,
51 interpolation is turned off).  Your config file will look something
52 like::
53
54   [project]
55   name: update-copyright
56   vcs: Git
57
58   [files]
59   authors: yes
60   files: yes
61   ignored: COPYING, README, .update-copyright.conf, .git*
62   pyfile: update_copyright/license.py
63
64   [copyright]
65   short: %(project)s comes with ABSOLUTELY NO WARRANTY and is licensed under the GNU General Public License.
66   long: This file is part of %(project)s.
67
68     %(project)s is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
69
70     %(project)s is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
71
72     You should have received a copy of the GNU General Public License along with %(project)s.  If not, see <http://www.gnu.org/licenses/>.
73
74 Options
75 -------
76
77 project/name
78   A string naming your project.  Replaces ``%(project)s`` in your
79   copyright blurbs.
80 project/vcs
81   The name of your version control system.
82 files/authors
83   Should ``update-copyright.py`` generate an ``AUTHORS`` file?
84   ``yes`` or ``no``.
85 files/files
86   Should ``update-copyright.py`` update copyright blurbs in versioned
87   files?  ``yes`` or ``no``.
88 files/ignored
89   A comma-separated list of globs matching files that should not have
90   copyright blurbs updated.  This protects files that may accidentally
91   caught by the blurb update algorithm.
92 files/pyfile
93   The path of an autogenerated license module, in case your program
94   wants to print out its copyright/licensing information.  If you
95   don't set this option, no license module will be generated.
96 copyright/short
97   A list of paragraphs (separated by blank lines) containing your
98   short copyright/license blurb.  This blurb is used in the pyfile's
99   ``short_license`` function (see `files/pyfile`).  This exists
100   because some programs print a short license blurb on startup, where
101   the full file-topping blurb may be overkill.
102 copyright/long
103   A list of paragraphs (separated by blank lines) containing your long
104   copyright/license blurb.  This blurb is used to replace copyright
105   blurbs in your source files.
106
107 Updating copyright blurbs
108 -------------------------
109
110 The blurb-update algorithm looks for any lines that begin with ``#
111 Copyright``.  These lines mark the beginning of a blurb, which
112 continues as long as subsequent lines begin with ``#``.  The old blurb
113 is replaced by a new blurb, which is automatically generated from your
114 configured long copyright string, with author names and edit years
115 extracted from the VCS data for that file.
116
117 Testing
118 =======
119
120 Run the internal unit tests with::
121
122     $ nosetests --with-doctest --doctest-tests update_copyright
123
124 Licence
125 =======
126
127 This project is distributed under the `GNU General Public License
128 Version 3`_ or greater.
129
130 Author
131 ======
132
133 W. Trevor King
134 wking@drexel.edu
135
136
137 .. _Bugs Everywhere: http://bugseverywhere.org/
138 .. _Gentoo: http://www.gentoo.org/
139 .. _layman: http://layman.sourceforge.net/
140 .. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay
141 .. _Git: http://git-scm.com/
142 .. _homepage: http://blog.tremily.us/posts/update-copyright/
143 .. _RawConfigParser:
144   http://docs.python.org/dev/library/configparser.html#configparser.RawConfigParser
145 .. _syntax documentation:
146   http://docs.python.org/dev/library/configparser.html#supported-ini-file-structure
147 .. _GNU General Public License Version 3: http://www.gnu.org/licenses/gpl.html