X-Git-Url: http://git.tremily.us/?p=update-copyright.git;a=blobdiff_plain;f=README;h=2a61b61767ee4fbed0b08a15ea6f1ffa9362336b;hp=06e2f897599ed3aa3d0e8cdf55dc6a826f07d98a;hb=afa81c33f834a6645ba3ee6830255a20c076f864;hpb=1f4d33e113cecdb1a83fba647107cbe76d80442b diff --git a/README b/README index 06e2f89..2a61b61 100644 --- a/README +++ b/README @@ -1,3 +1,5 @@ +.. -*- 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 @@ -38,7 +40,7 @@ Installing by hand See the homepage_ for details. To install the checkout, run the standard:: - $ python setup.py install + $ python setup.py install Usage ===== @@ -47,7 +49,7 @@ 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 ConfigParser_ (`syntax documentation`_, +parsed using Python's RawConfigParser_ (`syntax documentation`_, interpolation is turned off). Your config file will look something like:: @@ -114,12 +116,54 @@ 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 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 + $ nosetests --with-doctest --doctest-tests update_copyright Licence ======= @@ -131,17 +175,18 @@ Author ====== 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