Last updated: 2014-01-27 10:15:43 -0800
Upstream URL: git clone http://chriswarbo.net/git/wtk.git
Contents of README follows
.. -- 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.
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
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).
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
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] 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} 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/>.project/name A string naming your project. Replaces
{project} 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.
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.
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.
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
Run the internal unit tests with::
$ nosetests –with-doctest –doctest-tests update_copyright
This project is distributed under the
GNU General Public License Version 3_ or greater.
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/ .. _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