Here's my attempt at describing the third "mixed" approach to Gnulib
sources. Is it ok?
@node VCS Issues
@section Issues with Version Control Systems
If a project stores its source files in a version control system (VCS),
such as CVS, Subversion, or Git, one needs to decide which files to commit.
In principle, all files created by @code{gnulib-tool}, except
@file{gnulib-cache.m4}, can be treated like generated source files,
like for example a @file{parser.c} file generated from
@file{parser.y}. Alternatively, they can be considered source files
and updated manually.
Here are the three different approaches in common use. Each has its
place, and you should use whichever best suits your particular project
and development methods.
@enumerate
@item
In projects which commit all source files, whether generated or not,
into their VCS, the @code{gnulib-tool} generated files should all be
committed. In this case, you should pass the option
@samp{--no-vc-files} to @code{gnulib-tool}, which avoids alteration of
VCS-related files such as @file{.cvsignore}.
Gnulib also contains files generated by @command{make} (and removed by
@code{make clean}), using information determined by
@command{configure}. For a Gnulib source file of the form
@file{lib/foo.in.h}, the corresponding @file{lib/foo.h} is such a
@command{make}-generated file. These should @emph{not} be checked
into the VCS, but instead added to @file{.cvsignore} or equivalent.
@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.sh}, will typically contain the
statement for restoring the omitted files:
@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.
@item
Some projects take a ``middle road'': they do commit Gnulib source
files as in the first approach, but they do not commit other derived
files, such as a @code{Makefile.in} generated by Automake. This
increases the size and complexity of the repository, but can help
occasional contributors by not requiring them to have a full Gnulib
checkout to do a build, and all developers by ensuring that all
developers are working with the same version of Gnulib in the
repository. It also supports multiple Gnulib instances within a
project. It remains important not to commit the
@command{make}-generated files, as described above.
@end enumerate
