Eric Blake wrote: > > The contents of gnulib-cache.m4 is an output of the invocation of > > gnulib-tool, > > and therefore a derivative of the parameters that you pass to gnulib-tool. > > But the current documentation says that 'gnulib-cache.m4' is the ONE > output that you SHOULD be keeping in version control. In fact, that is > precisely how m4 works - by versioning just gnulib-cache.m4, it is > sufficient to have bootstrap run 'gnulib-tool --update' so that all > other developers will pick up the same set of modules as the last > developer that made a modification via gnulib-tool --import.
I've now updated the documentation, through the patch below. The changed sections are published here: <http://www.gnu.org/software/gnulib/manual/html_node/Modified-imports.html> <http://www.gnu.org/software/gnulib/manual/html_node/VCS-Issues.html> 2010-09-04 Bruno Haible <br...@clisp.org> Update doc about gnulib-tool. * doc/gnulib-tool.texi (VCS Issues): Explain 'gnulib-tool --import' vs. 'gnulib-tool --update' in more detail. Reported by Eric Blake. --- doc/gnulib-tool.texi.orig Sat Sep 4 19:25:18 2010 +++ doc/gnulib-tool.texi Sat Sep 4 19:24:15 2010 @@ -594,20 +594,34 @@ @item In projects which customarily omit from their VCS all files that are generated from other source files, none of these files and directories -are added into the VCS. The only file that must be added to the VCS -is @file{gnulib-cache.m4} in the M4 macros directory. Also, the -script for restoring files not in the VCS, customarily called -...@file{autogen.sh} or @file{bootstrap}, will typically contain the -statement for restoring the omitted files: +are added into the VCS. As described in @ref{Modified imports}, there +are two ways to keep track of options and module names that are passed +to @code{gnulib-tool}. The command for restoring the omitted files +depends on it: + +...@itemize @bullet +...@item +If they are stored in a file other than @code{gnulib-cache.m4}, such as +...@file{autogen.sh}, @file{bootstrap}, @file{bootstrap.conf}, or similar, +the restoration command is the entire @code{gnulib-tool ... --import ...} +invocation with all options and module names. + +...@item +If the project relies on @code{gnulib-tool}'s memory of the last used +options and module names, then the file @file{gnulib-cache.m4} in the M4 +macros directory must be added to the VCS, and the restoration command +is: @smallexample $ gnulib-tool --update @end smallexample -The @samp{--update} option operates much like the @samp{--import} option, -but it does not offer the possibility to change the way Gnulib is used. -Also it does not report in the ChangeLogs the files that it had to add -because they were missing. +The @samp{--update} option operates much like the @samp{--add-import} +option, but it does not offer the possibility to change the way Gnulib is +used. Also it does not report in the ChangeLogs the files that it had to +add because they were missing. + +...@end itemize Gnulib includes the file @file{build-aux/bootstrap} to aid a developer in using this setup. Furthermore, in projects that use git for
