Automatically update copyright blurbs in versioned source.

## Project description

.. -*- 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
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

Dependencies
------------

update-copyright is a simple package with no external dependencies
outside of the VCS commands themselves (e.g. you need git in your
PATH to use the Git_ backend, and hg in your PATH to use the
Mercurial_ backend).

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_ and Mercurial_, 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]
vcs: Git

[files]
authors: yes
files: yes

long: This file is part of {project}.

{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} 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}. If not, see <http://www.gnu.org/licenses/>.

Options
-------

project.name
A string naming your project. Replaces {project} in your
copyright blurbs. If this isn't set, update-copyright will fall
back to using the name of the repository directory.
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 pipe-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
wants to print out its copyright/licensing information. If you
don't set this option, no license module will be generated.
A list of paragraphs (separated by blank lines) containing your
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.
A list of paragraphs (separated by blank lines) containing your long

-------------------------

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.

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::

Licence
=======

Version 3_ or greater.

Author
======

W. Trevor King
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/
.. _Git: http://git-scm.com/
.. _Mercurial: http://mercurial.selenic.com/
.. _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

## Project details

Uploaded source`