+.. -*- coding: utf-8 -*-
+
``update-copyright`` is an automatic copyright updating tool. I wrote
the original for `Bugs Everywhere`_, but ended up copying it into a
number of my projects. Copying is bad, so here it is, split out as
See the homepage_ for details. To install the checkout, run the
standard::
- $ python setup.py install
+ $ python setup.py install
Usage
=====
(currently Git, Mercurial, and Bazaar, but it should be pretty easy to
add backends for other systems). You'll also need a config file
called ``.update-copyright.conf`` in your package root, which will be
-parsed using Python's ConfigParser_ (`syntax documentation`_,
+parsed using Python's RawConfigParser_ (`syntax documentation`_,
interpolation is turned off). Your config file will look something
like::
pyfile: update_copyright/license.py
[copyright]
- short: %(project)s comes with ABSOLUTELY NO WARRANTY and is licensed under the GNU General Public License.
- long: This file is part of %(project)s.
+ short: {project} comes with ABSOLUTELY NO WARRANTY and is licensed under the GNU General Public License.
+ long: This file is part of {project}.
- %(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.
+ {project} 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.
- %(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.
+ {project} 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.
- You should have received a copy of the GNU General Public License along with %(project)s. If not, see <http://www.gnu.org/licenses/>.
+ You should have received a copy of the GNU General Public License along with {project}. If not, see <http://www.gnu.org/licenses/>.
Options
-------
project/name
- A string naming your project. Replaces ``%(project)s`` in your
+ A string naming your project. Replaces ``{project}`` in your
copyright blurbs.
project/vcs
The name of your version control system.
configured long copyright string, with author names and edit years
extracted from the VCS data for that file.
+While the above works well for languages that use ``#`` to mark
+comment lines, it doesn't work for languages like C that use ``/*…*/``
+to mark comments. There blurb-update algorithm also looks for any
+lines that begging with ``/* Copyright`` and replaces that line, and
+subsequent lines up to one beginning with `` */``, with a new blurb.
+
+Because I've never seen a file with *both* trigger lines, it shouldn't
+be a problem to run both against each of your versioned files. If it
+is a problem for you, let me know, and we can add some configuration
+options to work around the problem.
+
+Incomplete VCS history
+----------------------
+
+Sometimes files have authors or alterations not recorded in a
+project's VCS history. You can use the ``author-hacks`` section to
+add authors to a file, and the ``year-hacks`` section to adjust the
+files original year. Author names should be pipe-separated. For
+example::
+
+ [author-hacks]
+ path/to/file: John Doe <jdoe@a.com> | Jane Smith <jsmith@b.net>
+
+ [year-hacks]
+ path/to/another/file: 2009
+
+Add entries for as many files as you like. Paths should be relative
+to your project root. Always use forward slashes (``/``) to separate
+path elements.
+
+Aliases
+-------
+
+Occasionally names or email addresses used when committing to the VCS
+will go out of date. Some VCSs have a built-in method of dealing with
+this (e.g. Git's .mailmap_). For those without such a VCS, you can
+add an `aliases`` section to your config file, where the option names
+are the canonical name of the ...?. For example::
+
+ [aliases]
+ John Doe <jdoe@a.com>: John Doe | jdoe | J. Doe <j@doe.net>
+
Testing
=======
Run the internal unit tests with::
- $ nosetests --with-doctest --doctest-tests update_copyright
+ $ nosetests --with-doctest --doctest-tests update_copyright
Licence
=======
======
W. Trevor King
-wking@drexel.edu
+wking@tremily.us
.. _Bugs Everywhere: http://bugseverywhere.org/
.. _Gentoo: http://www.gentoo.org/
.. _layman: http://layman.sourceforge.net/
-.. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay
+.. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay/
.. _Git: http://git-scm.com/
.. _homepage: http://blog.tremily.us/posts/update-copyright/
-.. _ConfigParser:
- http://docs.python.org/dev/library/configparser.html#configparser.ConfigParser
+.. _RawConfigParser:
+ http://docs.python.org/dev/library/configparser.html#configparser.RawConfigParser
.. _syntax documentation:
http://docs.python.org/dev/library/configparser.html#supported-ini-file-structure
+.. _.mailmap: http://schacon.github.com/git/git-shortlog.html#_mapping_authors
.. _GNU General Public License Version 3: http://www.gnu.org/licenses/gpl.html