1 .. -*- coding: utf-8 -*-
3 ``update-copyright`` is an automatic copyright updating tool. I wrote
4 the original for `Bugs Everywhere`_, but ended up copying it into a
5 number of my projects. Copying is bad, so here it is, split out as
6 its own separate project.
17 I've packaged ``update-copyright`` for Gentoo_. You need layman_ and
18 my `wtk overlay`_. Install with::
20 # emerge -av app-portage/layman
22 # emerge -av dev-util/update-copyright
27 ``update-copyright`` is a simple package with no external dependencies
28 outside of the VCS commands themselves (e.g. you need `git` in your
29 `PATH` to use the Git_ backend, and `hg` in your `PATH` to use the
35 ``update-copyright`` is available as a Git_ repository::
37 $ git clone git://tremily.us/update-copyright.git
39 See the homepage_ for details. To install the checkout, run the
42 $ python setup.py install
47 You'll need a project that you version with one of our supported VCSs
48 (currently Git_ and Mercurial_, but it should be pretty easy to add
49 backends for other systems). You'll also need a config file called
50 ``.update-copyright.conf`` in your package root, which will be parsed
51 using Python's RawConfigParser_ (`syntax documentation`_,
52 interpolation is turned off). Your config file will look something
56 name: update-copyright
62 ignored: COPYING | README | .update-copyright.conf | .git*
63 pyfile: update_copyright/license.py
66 short: {project} comes with ABSOLUTELY NO WARRANTY and is licensed under the GNU General Public License.
67 long: This file is part of {project}.
69 {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.
71 {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.
73 You should have received a copy of the GNU General Public License along with {project}. If not, see <http://www.gnu.org/licenses/>.
79 A string naming your project. Replaces ``{project}`` in your
82 The name of your version control system.
84 Should ``update-copyright.py`` generate an ``AUTHORS`` file?
87 Should ``update-copyright.py`` update copyright blurbs in versioned
88 files? ``yes`` or ``no``.
90 A pipe-separated list of globs matching files that should not have
91 copyright blurbs updated. This protects files that may accidentally
92 caught by the blurb update algorithm.
94 The path of an autogenerated license module, in case your program
95 wants to print out its copyright/licensing information. If you
96 don't set this option, no license module will be generated.
98 A list of paragraphs (separated by blank lines) containing your
99 short copyright/license blurb. This blurb is used in the pyfile's
100 ``short_license`` function (see `files/pyfile`). This exists
101 because some programs print a short license blurb on startup, where
102 the full file-topping blurb may be overkill.
104 A list of paragraphs (separated by blank lines) containing your long
105 copyright/license blurb. This blurb is used to replace copyright
106 blurbs in your source files.
108 Updating copyright blurbs
109 -------------------------
111 The blurb-update algorithm looks for any lines that begin with ``#
112 Copyright``. These lines mark the beginning of a blurb, which
113 continues as long as subsequent lines begin with ``#``. The old blurb
114 is replaced by a new blurb, which is automatically generated from your
115 configured long copyright string, with author names and edit years
116 extracted from the VCS data for that file.
118 While the above works well for languages that use ``#`` to mark
119 comment lines, it doesn't work for languages like C that use ``/*…*/``
120 to mark comments. There blurb-update algorithm also looks for any
121 lines that begging with ``/* Copyright`` and replaces that line, and
122 subsequent lines up to one beginning with `` */``, with a new blurb.
124 Because I've never seen a file with *both* trigger lines, it shouldn't
125 be a problem to run both against each of your versioned files. If it
126 is a problem for you, let me know, and we can add some configuration
127 options to work around the problem.
129 Incomplete VCS history
130 ----------------------
132 Sometimes files have authors or alterations not recorded in a
133 project's VCS history. You can use the ``author-hacks`` section to
134 add authors to a file, and the ``year-hacks`` section to adjust the
135 files original year. Author names should be pipe-separated. For
139 path/to/file: John Doe <jdoe@a.com> | Jane Smith <jsmith@b.net>
142 path/to/another/file: 2009
144 Add entries for as many files as you like. Paths should be relative
145 to your project root. Always use forward slashes (``/``) to separate
151 Occasionally names or email addresses used when committing to the VCS
152 will go out of date. Some VCSs have a built-in method of dealing with
153 this (e.g. Git's `.mailmap`_). For those without such a VCS, you can
154 add an `aliases`` section to your config file, where the option names
155 are the canonical name of the ...?. For example::
158 John Doe <jdoe@a.com>: John Doe | jdoe | J. Doe <j@doe.net>
163 Run the internal unit tests with::
165 $ nosetests --with-doctest --doctest-tests update_copyright
170 This project is distributed under the `GNU General Public License
171 Version 3`_ or greater.
180 .. _Bugs Everywhere: http://bugseverywhere.org/
181 .. _Gentoo: http://www.gentoo.org/
182 .. _layman: http://layman.sourceforge.net/
183 .. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay/
184 .. _Git: http://git-scm.com/
185 .. _Mercurial: http://mercurial.selenic.com/
186 .. _homepage: http://blog.tremily.us/posts/update-copyright/
188 http://docs.python.org/dev/library/configparser.html#configparser.RawConfigParser
189 .. _syntax documentation:
190 http://docs.python.org/dev/library/configparser.html#supported-ini-file-structure
191 .. _.mailmap: http://schacon.github.com/git/git-shortlog.html#_mapping_authors
192 .. _GNU General Public License Version 3: http://www.gnu.org/licenses/gpl.html