``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
its own separate project.
Installation
============
Packages
--------
Gentoo
~~~~~~
I've packaged ``update-copyright`` for Gentoo_. You need layman_ and
my `wtk overlay`_. Install with::
# emerge -av app-portage/layman
# layman --add wtk
# emerge -av dev-util/update-copyright
Dependencies
------------
``update-copyright`` is a simple package with few external
dependencies. The only external dependencies are the Python packages
behind Python-based version control systems. If you're using those
VCSs, you've already installed the packages. If you're not using
those VCSs, you don't need the packages.
Installing by hand
------------------
``update-copyright`` is available as a Git_ repository::
$ git clone git://tremily.us/update-copyright.git
See the homepage_ for details. To install the checkout, run the
standard::
$ python setup.py install
Usage
=====
You'll need a project that you version with one of our supported VCSs
(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 RawConfigParser_ (`syntax documentation`_,
interpolation is turned off). Your config file will look something
like::
[project]
name: update-copyright
vcs: Git
[files]
authors: yes
files: yes
ignored: COPYING, README, .update-copyright.conf, .git*
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.
%(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)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.
You should have received a copy of the GNU General Public License along with %(project)s. If not, see .
Options
-------
project/name
A string naming your project. Replaces ``%(project)s`` in your
copyright blurbs.
project/vcs
The name of your version control system.
files/authors
Should ``update-copyright.py`` generate an ``AUTHORS`` file?
``yes`` or ``no``.
files/files
Should ``update-copyright.py`` update copyright blurbs in versioned
files? ``yes`` or ``no``.
files/ignored
A comma-separated list of globs matching files that should not have
copyright blurbs updated. This protects files that may accidentally
caught by the blurb update algorithm.
files/pyfile
The path of an autogenerated license module, in case your program
wants to print out its copyright/licensing information. If you
don't set this option, no license module will be generated.
copyright/short
A list of paragraphs (separated by blank lines) containing your
short copyright/license blurb. This blurb is used in the pyfile's
``short_license`` function (see `files/pyfile`). This exists
because some programs print a short license blurb on startup, where
the full file-topping blurb may be overkill.
copyright/long
A list of paragraphs (separated by blank lines) containing your long
copyright/license blurb. This blurb is used to replace copyright
blurbs in your source files.
Updating copyright blurbs
-------------------------
The blurb-update algorithm looks for any lines that begin with ``#
Copyright``. These lines mark the beginning of a blurb, which
continues as long as subsequent lines begin with ``#``. The old blurb
is replaced by a new blurb, which is automatically generated from your
configured long copyright string, with author names and edit years
extracted from the VCS data for that file.
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 comma-separated. For
example::
[author-hacks]
path/to/file: John Doe , Jane Smith
[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 : John Doe, jdoe, J. Doe
Testing
=======
Run the internal unit tests with::
$ nosetests --with-doctest --doctest-tests update_copyright
Licence
=======
This project is distributed under the `GNU General Public License
Version 3`_ or greater.
Author
======
W. Trevor King
wking@drexel.edu
.. _Bugs Everywhere: http://bugseverywhere.org/
.. _Gentoo: http://www.gentoo.org/
.. _layman: http://layman.sourceforge.net/
.. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay/
.. _Git: http://git-scm.com/
.. _homepage: http://blog.tremily.us/posts/update-copyright/
.. _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