From unknown Sat Jun 14 03:52:25 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#38332 <38332@debbugs.gnu.org> To: bug#38332 <38332@debbugs.gnu.org> Subject: Status: document --initialize for vc-dwim [patch] Reply-To: bug#38332 <38332@debbugs.gnu.org> Date: Sat, 14 Jun 2025 10:52:25 +0000 retitle 38332 document --initialize for vc-dwim [patch] reassign 38332 vc-dwim submitter 38332 Karl Berry severity 38332 normal tag 38332 patch thanks From debbugs-submit-bounces@debbugs.gnu.org Fri Nov 22 17:50:02 2019 Received: (at submit) by debbugs.gnu.org; 22 Nov 2019 22:50:03 +0000 Received: from localhost ([127.0.0.1]:55672 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iYHkW-0006dL-Me for submit@debbugs.gnu.org; Fri, 22 Nov 2019 17:50:02 -0500 Received: from lists.gnu.org ([209.51.188.17]:44312) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iYHkQ-0006d8-RQ for submit@debbugs.gnu.org; Fri, 22 Nov 2019 17:49:55 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:45621) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iYHkP-0003XF-C8 for bug-vc-dwim@gnu.org; Fri, 22 Nov 2019 17:49:54 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-1.5 required=5.0 tests=BAYES_50,RCVD_IN_DNSWL_MED, URIBL_BLOCKED autolearn=disabled version=3.3.2 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iYHkL-0004vO-Nm for bug-vc-dwim@gnu.org; Fri, 22 Nov 2019 17:49:51 -0500 Received: from freefriends.org ([96.88.95.60]:55970) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1iYHkH-0004rm-DH for bug-vc-dwim@gnu.org; Fri, 22 Nov 2019 17:49:47 -0500 X-Envelope-From: karl@freefriends.org X-Envelope-To: Received: from freefriends.org (freefriends.org [96.88.95.60]) by freefriends.org (8.14.7/8.14.7) with ESMTP id xAMMndcZ004325 (version=TLSv1/SSLv3 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT) for ; Fri, 22 Nov 2019 15:49:39 -0700 Received: (from apache@localhost) by freefriends.org (8.14.7/8.14.7/Submit) id xAMMnc1b004322; Fri, 22 Nov 2019 15:49:38 -0700 Date: Fri, 22 Nov 2019 15:49:38 -0700 Message-Id: <201911222249.xAMMnc1b004322@freefriends.org> From: Karl Berry To: bug-vc-dwim@gnu.org Subject: document --initialize for vc-dwim [patch] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 96.88.95.60 X-Spam-Score: -1.4 (-) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.4 (--) 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 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 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 file +in the top-level directory, running B first +renames it to C. =item B<--help>