GNU bug report logs - #38332
document --initialize for vc-dwim [patch]

Previous Next

Full log

View this message in rfc822 format

From: Karl Berry <karl <at> freefriends.org>
To: 38332 <at> debbugs.gnu.org
Subject: bug#38332: document --initialize for vc-dwim [patch]
Date: Fri, 22 Nov 2019 15:49:38 -0700

I suspect I did not format the ChangeLog entry (or the diff) ideally,
but I hope it will suffice to be usable. -k

2019-11-14  Karl Berry  <karl <at> freefriends.org>

	doc: Document vc-dwim --initialize in manual.
	
	* vc-dwim.pl: reword --initialize documentation.
	* doc/vc-dwim.texi (Initializing vc-dwim): new node.
	(vc-dwim Invocation): mention --initialize; move most of
	description to new node.

--- doc/vc-dwim.texi	2019-11-13 17:36:14.920575492 -0800
+++ init.texi	2019-11-14 18:31:13.419347192 -0800
@@ -129,4 +129,5 @@
 @menu
 * Using vc-dwim::               How can you use vc-dwim?
+* Initializing vc-dwim::        Setting up a source tree with no ChangeLog file
 * vc-dwim Invocation::          Invoking vc-dwim
 @end menu
@@ -193,4 +194,33 @@
 
 
+@node Initializing vc-dwim
+@section Initializing vc-dwim
+
+vc-dwim operates based on a ChangeLog file; if you maintain a ChangeLog
+as part of your source tree, you don't need to do anything special to
+set up to use vc-dwim; just run it.
+
+However, it is common practice nowadays for source trees not to have
+ChangeLog files, but instead to have them derived for distributions or
+on demand (@code{make ChangeLog}, with a hone common GNU infrastructure).
+So, how to use vc-dwim in this case? It still needs a ChangeLog.
+
+The answer is to run @code{vc-dwim --initialize}. This sets up your own,
+private @file{ChangeLog} file in a git repository rooted at
+@file{@var{VCDIR}/c/}, with a symlink to it from the top level directory
+of the source tree in which you'd like to use vc-dwim.
+
+Your own source tree need not use git; @var{VCDIR} in the above refers
+to the version-control system's control directory, such as @file{.svn},
+@file{_darcs}, etc., as well as @file{.git}.
+
+Then you can make ChangeLog entries as usual, and proceed with use of
+vc-dwim.
+
+You can also set up your own repository of whatever type and make your
+own symlinked top-level ChangeLog into it; there's nothing magical about
+@code{--initialize} or the @file{@var{VCDIR}/c/} location.
+
+
 @node vc-dwim Invocation
 @section Invoking vc-dwim
@@ -202,4 +232,5 @@
 vc-dwim @ovar{option...} --diff @ovar{file...}
 vc-dwim @ovar{option...} --print-vc-list
+vc-dwim @ovar{option...} --initialize
 @end example
 
@@ -227,11 +258,8 @@
 
 But what if you'd like to use @command{vc-dwim} on a project that
-doesn't have or want a @file{ChangeLog} file?  In that case, you can
-maintain your own, private, version-controlled @file{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 @file{ChangeLog} file need not
-even use the same version control system as the rest of the project
-hierarchy.
+doesn't have or want a @file{ChangeLog} file? In that case, you can
+maintain your own ChangeLog file.  This is what the
+@option{--initialize} option sets up for you, or you can perform
+equivalent steps by hand (@pxref{Initializing vc-dwim}).
 
 @noindent
@@ -261,4 +289,8 @@
 Print the list of recognized version control names, then exit.
 
+@item --initialize
+Prepare a source tree with no @file{ChangeLog} file for use with vc-dwim
+(@pxref{Initializing vc-dwim}).
+
 @item --verbose
 Generate verbose output.
--- vc-dwim.pl	2019-11-13 17:36:14.932575295 -0800
+++ init.pl	2019-11-17 18:31:47.178192024 -0800
@@ -1234,12 +1234,12 @@
 =item B<--initialize>
 
-This option is useful in a project that does not version-control
-a ChangeLog file.  Use this option in the top-level project
-directory to create your personal ChangeLog file -- that file
-will be a symlink to a git-version-controlled ChangeLog file
-in a just-created single-file repository residing in the VC-admin
-directory (.git, .hg, etc.).  If there is an existing ChangeLog file
-in the working directory, running B<vc-dwim --initialize> first
-renames it to ChangeLog~.
+This option, or the equivalent operations, is needed in a project that
+does not version-control a ChangeLog file. Use this option in the
+top-level project directory to create your personal ChangeLog file --
+that file will be a symlink to a git-version-controlled ChangeLog file
+in a just-created single-file repository residing in the VC admin
+directory (.git, .hg, etc.). If there is an existing C<ChangeLog> file
+in the top-level directory, running B<vc-dwim --initialize> first
+renames it to C<ChangeLog~>.
 
 =item B<--help>

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.