Re: April 7 cutover for generating ChangeLog automatically

[Paul Eggert <eggert@cs.ucla.edu>]

[-- Attachment #1: Type: text/plain, Size: 454 bytes --]

nicolas.petton@foretagsplatsen.se wrote:
> what does "create a ChangeLog symlink a la
> vc-dwim" mean? And what does `vc-dwim --commit' does?

If you have vc-dwim installed, 'vc-dwim --help' should explain both points. 
I've attached its output.  For the first question, please see the last paragraph 
of the DESCRIPTION, and the EXAMPLE.  For the second question, please see the 
first two paragraphs of DESCRIPTION, and the first option under OPTIONS.

[-- Attachment #2: vc-dwim-help.txt --]
[-- Type: text/plain, Size: 4025 bytes --]

NAME
    vc-dwim - use new ChangeLog entries to direct and cross-check a
    version-control "diff" or "commit" command

SYNOPSIS
    vc-dwim [OPTIONS] [CHANGELOG_FILE...]

    vc-dwim [OPTIONS] --commit CHANGELOG_FILE...

    vc-dwim [OPTIONS] --diff [FILE...]

    vc-dwim [OPTIONS] --print-vc-list

DESCRIPTION
    By default, each command line argument should be a locally modified,
    version-controlled ChangeLog file.  If there is no command line argument,
    vc-dwim tries to use the ChangeLog file in the current directory.  In this
    default mode, vc-dwim works by first computing diffs of those files and
    parsing the diff output to determine which named files are being changed. 
    Then, it diffs the affected files and prints the resulting output.  One
    advantage of using this tool is that before printing any diffs, it warns
    you if it sees that a ChangeLog or an affected file has unsaved changes. 
    It detects that by searching for an editor temporary file corresponding to
    each affected file.  Another common error you can avoid with this tool is
    the one where you create a new file, add its name to Makefiles, etc.,
    mention the addition in ChangeLog, but forget to e.g., "git add" (or "hg
    add", etc.) the file to the version control system.  vc-dwim detects this
    discrepancy and fails with a diagnostic explaining the probable situation.
    You might also have simply mistyped the file name in the ChangeLog.

    Once you are happy with your ChangeLog-derived diffs, you can commit those
    changes and the ChangeLog simply by rerunning the command with the
    --commit option.

    But what if you'd like to use vc-dwim on a project that doesn't have or
    want a ChangeLog file?  In that case, you can maintain your own, private,
    version-controlled ChangeLog file in a different hierarchy.  Then just
    make a symlink to it from the top level directory of the hierarchy in
    which you'd like to use it and everything should work.  Your private
    ChangeLog file need not even use the same version control system as the
    rest of the project hierarchy.

OPTIONS
    --commit
        perform the commit, too

    --author="User Name <user@example.org>"
        Specify the user name and email address of the author of this change
        set.

    --diff
        Determine which version control system manages the first FILE, then
        use that to print diffs of the named FILEs.  If no FILE is specified,
        print all diffs for the current hierarchy.

    --print-vc-list
        Print the list of recognized version control names, then exit.

    --help
        Display this help and exit.

    --version
        Output version information and exit.

    --verbose
        Generate verbose output.

    --debug
        Generate debug output.

EXAMPLE
    Here's how to use vc-dwim in a project that does not version-control a
    ChangeLog file.  Create a repository just for your personal ChangeLog file
    and make a symlink to it from the top-level directory of the project.  For
    projects that use git, I put this tiny auxiliary repository in a directory
    named .git/c.  You can use this bash/zsh alias to set it up and to create
    the symlink:

        git-changelog-symlink-init()
        {
            local d=.git/c
            test -d .git || return 1
            mkdir $d
            touch $d/ChangeLog
            (cd $d && git init && git add ChangeLog && git commit -m. -a)
            ln --backup -s $d/ChangeLog .
        }

RESTRICTIONS
    This tool can be useful to you only if you use a version control system. 
    It's most useful if you maintain a ChangeLog file and create a log entry
    per file per "commit" operation.

    Relies on fairly strict adherence to recommended ChangeLog syntax. 
    Detects editor temporaries created by Emacs and Vim.  Eventually, it will
    detect temporaries created by other editors.

AUTHOR
    Jim Meyering <jim@meyering.net>

    Report bugs to <bug-vc-dwim@gnu.org>.