Package: update-copyright
.. -*- coding: utf-8 -*-``update-copyright`` is an automatic copyright updating tool.  I wrotethe original for `Bugs Everywhere`_, but ended up copying it into anumber of my projects.  Copying is bad, so here it is, split out asits own separate project.Installation============Packages--------Gentoo~~~~~~I've packaged ``update-copyright`` for Gentoo_.  You need layman_ andmy `wtk overlay`_.  Install with::# emerge -av app-portage/layman# layman --add wtk# emerge -av dev-util/update-copyrightDependencies------------``update-copyright`` is a simple package with no external dependenciesoutside 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 theMercurial_ backend).Installing by hand------------------``update-copyright`` is available as a Git_ repository::$ git clone git://tremily.us/update-copyright.gitSee the homepage_ for details.  To install the checkout, run thestandard::$ python setup.py installUsage=====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 addbackends for other systems).  You'll also need a config file called``.update-copyright.conf`` in your package root, which will be parsedusing Python's RawConfigParser_ (`syntax documentation`_,interpolation is turned off).  Your config file will look somethinglike::[project]name: update-copyrightvcs: Git[files]authors: yesfiles: yesignored: COPYING | README | .update-copyright.conf | .git*pyfile: update_copyright/license.py[copyright]short: {project} comes with ABSOLUTELY NO WARRANTY and is licensed under the GNU General Public License.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.nameA string naming your project.  Replaces ``{project}`` in yourcopyright blurbs.  If this isn't set, ``update-copyright`` will fallback to using the name of the repository directory.project.vcsThe name of your version control system.files.authorsShould ``update-copyright.py`` generate an ``AUTHORS`` file?``yes`` or ``no``.files.filesShould ``update-copyright.py`` update copyright blurbs in versionedfiles?  ``yes`` or ``no``.files.ignoredA pipe-separated list of globs matching files that should not havecopyright blurbs updated.  This protects files that may accidentallycaught by the blurb update algorithm.files.pyfileThe path of an autogenerated license module, in case your programwants to print out its copyright/licensing information.  If youdon't set this option, no license module will be generated.copyright.shortA list of paragraphs (separated by blank lines) containing yourshort copyright/license blurb.  This blurb is used in the pyfile's``short_license`` function (see `files.pyfile`).  This existsbecause some programs print a short license blurb on startup, wherethe full file-topping blurb may be overkill.copyright.longA list of paragraphs (separated by blank lines) containing your longcopyright/license blurb.  This blurb is used to replace copyrightblurbs 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, whichcontinues as long as subsequent lines begin with ``#``.  The old blurbis replaced by a new blurb, which is automatically generated from yourconfigured long copyright string, with author names and edit yearsextracted from the VCS data for that file.While the above works well for languages that use ``#`` to markcomment lines, it doesn't work for languages like C that use ``/*…*/``to mark comments.  There blurb-update algorithm also looks for anylines that begging with ``/* Copyright`` and replaces that line, andsubsequent lines up to one beginning with `` */``, with a new blurb.Because I've never seen a file with *both* trigger lines, it shouldn'tbe a problem to run both against each of your versioned files.  If itis a problem for you, let me know, and we can add some configurationoptions to work around the problem.Incomplete VCS history----------------------Sometimes files have authors or alterations not recorded in aproject's VCS history.  You can use the ``author-hacks`` section toadd authors to a file, and the ``year-hacks`` section to adjust thefiles original year.  Author names should be pipe-separated.  Forexample::[author-hacks]path/to/file: John Doe <jdoe@a.com> | Jane Smith <jsmith@b.net>[year-hacks]path/to/another/file: 2009Add entries for as many files as you like.  Paths should be relativeto your project root.  Always use forward slashes (``/``) to separatepath elements.Aliases-------Occasionally names or email addresses used when committing to the VCSwill go out of date.  Some VCSs have a built-in method of dealing withthis (e.g. Git's `.mailmap`_).  For those without such a VCS, you canadd an `aliases`` section to your config file, where the option namesare 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_copyrightLicence=======This project is distributed under the `GNU General Public LicenseVersion 3`_ or greater.Author======W. Trevor Kingwking@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/.. _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