Peter Krefting <peter@xxxxxxxxxxxxxxxx> writes: > +=head1 NAME > + > +import-directories - Import bits and pieces to Git. > + > +=head1 SYNOPSIS > + > +B<import-directories.perl> F<configfile> > + > +=head1 DESCRIPTION > + > +Script to import arbitrary projects version controlled by the "copy the > +source directory to a new location and edit it there"-version controlled > +projects into version control. Handles projects with arbitrary branching > +and version trees, taking a file describing the inputs and generating a > +file compatible with the L<git-fast-import(1)> format. Nice write-up. > +=head1 CONFIGURATION FILE > + > +=head2 Format > + > +The configuration file is using a standard I<.ini> format. You might want to mention that this format is different from what git uses for its .git/config and .gitmodules files, and none of the rules apply to them (namely, two/three-level names, case sensitivity, allowed letters in variable names, stripping of whitespaces around values, and value quoting) described in 'git help config' apply to this file. It was the first "huh" I had when reading your description below, when you used "[3]" as a section name and "source.c" as a variable. > +=head2 Revision configuration > + > +Each revision that is to be imported is described in three > +sections. Sections should be defined chronologically, so that a > +revision's parent has always been defined when a new revision > +is introduced. All sections for one revision should be defined > +before defining the next revision. > + > +Revisions are specified numerically, but they numbers need not be > +consecutive, only unique. You might want to clarify that they do not need to be monotonically increasing either---you can have #3 as the root and then #1 with its parent set to #3, right? As you seem to be supporting merges, you might want to say topologically instead of chronologically---this is minor, as you give more precise definition "all parents must come before a child" in that sentence later. > + timestamp=3/source.c > + ... > +=head3 Revision contents section > + > +A section whose section name is an integer followed by B<.files> > +describes the files included in this revision. To somebody who knows git it may be obvious but perhaps "describes all the files" (or "lists all the files") would be clearer? Otherwise, a naive reader might be frustrated by getting unexpected results after listing only modified or added files in this section. > + [3.files] > + ; the key is the path inside the repository, the value is the path > + ; as seen from the importer script. > + source.c=3/source.c > + source.h=3/source.h How are problematic characters in pathnames (say, SP, '=' or worse LF) handled? Do they need to be quoted, and if so how? As an example in the documentation, 3/source.c is a bit unfortunate. It may be risking to get misunderstood that somehow the directory name must match the revision label (numeric section name), which I think is not what you meant to say here. Perhaps use something like: source.c = project-v0.0.3/soruce.c to clarify? > +=head3 Revision commit message section > + > +A section whose section name is an integer followed by B<.message> > +gives the commit message. This section is read verbatim. Meaning "everything up to the beginning of the next section"? Can a commit message have a line that begins with a '[', perhaps as long as it does not contain a matching ']', so that such a line does not misinterpreted as starting a new, possibly invalid, section? -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html