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.
15 I've packaged ``update-copyright`` for Gentoo_. You need layman_ and
16 my `wtk overlay`_. Install with::
18 # emerge -av app-portage/layman
20 # emerge -av dev-util/update-copyright
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.
34 ``update-copyright`` is available as a Git_ repository::
36 $ git clone git://tremily.us/update-copyright.git
38 See the homepage_ for details. To install the checkout, run the
41 $ python setup.py install
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
55 name: update-copyright
61 ignored: COPYING, README, .update-copyright.conf, .git*
62 pyfile: update_copyright/license.py
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.
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.
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.
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/>.
78 A string naming your project. Replaces ``%(project)s`` in your
81 The name of your version control system.
83 Should ``update-copyright.py`` generate an ``AUTHORS`` file?
86 Should ``update-copyright.py`` update copyright blurbs in versioned
87 files? ``yes`` or ``no``.
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.
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.
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.
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.
107 Updating copyright blurbs
108 -------------------------
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.
117 Incomplete VCS history
118 ----------------------
120 Sometimes files have authors or alterations not recorded in a
121 project's VCS history. You can use the ``author-hacks`` section to
122 add authors to a file, and the ``year-hacks`` section to adjust the
123 files original year. Author names should be comma-separated. For
127 path/to/file: John Doe <jdoe@a.com>, Jane Smith <jsmith@b.net>
130 path/to/another/file: 2009
132 Add entries for as many files as you like. Paths should be relative
133 to your project root. Always use forward slashes (``/``) to separate
139 Occasionally names or email addresses used when committing to the VCS
140 will go out of date. Some VCSs have a built-in method of dealing with
141 this (e.g. Git's .mailmap_). For those without such a VCS, you can
142 add an `aliases`` section to your config file, where the option names
143 are the canonical name of the ...?. For example::
146 John Doe <jdoe@a.com>: John Doe, jdoe, J. Doe <j@doe.net>
151 Run the internal unit tests with::
153 $ nosetests --with-doctest --doctest-tests update_copyright
158 This project is distributed under the `GNU General Public License
159 Version 3`_ or greater.
168 .. _Bugs Everywhere: http://bugseverywhere.org/
169 .. _Gentoo: http://www.gentoo.org/
170 .. _layman: http://layman.sourceforge.net/
171 .. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay
172 .. _Git: http://git-scm.com/
173 .. _homepage: http://blog.tremily.us/posts/update-copyright/
175 http://docs.python.org/dev/library/configparser.html#configparser.RawConfigParser
176 .. _syntax documentation:
177 http://docs.python.org/dev/library/configparser.html#supported-ini-file-structure
178 .. _.mailmap: http://schacon.github.com/git/git-shortlog.html#_mapping_authors
179 .. _GNU General Public License Version 3: http://www.gnu.org/licenses/gpl.html