Merge pull request #181 from uetchy/preserve

add cli flag to prevent doctoc from adding toc to a file without toc.
this is good for CI or the combination with [`lint-staged`](https://github.com/okonet/lint-staged).
with -p, doctoc will update toc if md has toc sectioon, otherwise doctoc keep it unmodified.

I'm not sure `preserve` is the right name for it. so please change it if you have a better one.

Author: AndrewSouthpaw

README.md

@@ -140,6 +140,10 @@ You can print to stdout by using the `-s` or `--stdout` option.
 
 [ack]: http://beyondgrep.com/
 
+### Only update existing ToC
+
+Use `--update-only` or `-u` to only update the existing ToC. That is, the Markdown files without ToC will be left untouched. It is good if you want to use `doctoc` with `lint-staged`.
+
 ### Usage as a `git` hook
 
 doctoc can be used as a [pre-commit](http://pre-commit.com) hook by using the

doctoc.js

@@ -16,17 +16,21 @@ function cleanPath(path) {
   return homeExpanded.replace(/\s/g, '\\ ');
 }
 
-function transformAndSave(files, mode, maxHeaderLevel, title, notitle, entryPrefix, processAll, stdOut) {
+function transformAndSave(files, mode, maxHeaderLevel, title, notitle, entryPrefix, processAll, stdOut, updateOnly) {
   if (processAll) {
     console.log('--all flag is enabled. Including headers before the TOC location.')
   }
+
+  if (updateOnly) {
+    console.log('--update-only flag is enabled. Only updating files that already have a TOC.')
+  }
 
   console.log('\n==================\n');
 
   var transformed = files
     .map(function (x) {
       var content = fs.readFileSync(x.path, 'utf8')
-        , result = transform(content, mode, maxHeaderLevel, title, notitle, entryPrefix, processAll);
+        , result = transform(content, mode, maxHeaderLevel, title, notitle, entryPrefix, processAll, updateOnly);
       result.path = x.path;
       return result;
     });
@@ -58,7 +62,7 @@ function printUsageAndExit(isErr) {
 
   var outputFunc = isErr ? console.error : console.info;
 
-  outputFunc('Usage: doctoc [mode] [--entryprefix prefix] [--notitle | --title title] [--maxlevel level] [--all] <path> (where path is some path to a directory (e.g., .) or a file (e.g., README.md))');
+  outputFunc('Usage: doctoc [mode] [--entryprefix prefix] [--notitle | --title title] [--maxlevel level] [--all] [--update-only] <path> (where path is some path to a directory (e.g., .) or a file (e.g., README.md))');
   outputFunc('\nAvailable modes are:');
   for (var key in modes) {
     outputFunc('  --%s\t%s', key, modes[key]);
@@ -79,7 +83,7 @@ var modes = {
 var mode = modes['github'];
 
 var argv = minimist(process.argv.slice(2)
-    , { boolean: [ 'h', 'help', 'T', 'notitle', 's', 'stdout', 'all' ].concat(Object.keys(modes))
+    , { boolean: [ 'h', 'help', 'T', 'notitle', 's', 'stdout', 'all' , 'u', 'update-only'].concat(Object.keys(modes))
     , string: [ 'title', 't', 'maxlevel', 'm', 'entryprefix' ]
     , unknown: function(a) { return (a[0] == '-' ? (console.error('Unknown option(s): ' + a), printUsageAndExit(true)) : true); }
     });
@@ -99,6 +103,7 @@ var notitle = argv.T || argv.notitle;
 var entryPrefix = argv.entryprefix || '-';
 var processAll = argv.all;
 var stdOut = argv.s || argv.stdout
+var updateOnly = argv.u || argv['update-only']
 
 var maxHeaderLevel = argv.m || argv.maxlevel;
 if (maxHeaderLevel && isNaN(maxHeaderLevel) || maxHeaderLevel < 0) { console.error('Max. heading level specified is not a positive number: ' + maxHeaderLevel), printUsageAndExit(true); }
@@ -115,7 +120,7 @@ for (var i = 0; i < argv._.length; i++) {
     files = [{ path: target }];
   }
 
-  transformAndSave(files, mode, maxHeaderLevel, title, notitle, entryPrefix, processAll, stdOut);
+  transformAndSave(files, mode, maxHeaderLevel, title, notitle, entryPrefix, processAll, stdOut, updateOnly);
 
   console.log('\nEverything is OK.');
 }

lib/transform.js

@@ -106,7 +106,7 @@ function determineTitle(title, notitle, lines, info) {
   return info.hasStart ? lines[info.startIdx + 2] : defaultTitle;
 }
 
-exports = module.exports = function transform(content, mode, maxHeaderLevel, title, notitle, entryPrefix, processAll) {
+exports = module.exports = function transform(content, mode, maxHeaderLevel, title, notitle, entryPrefix, processAll, updateOnly) {
   mode = mode || 'github.com';
   entryPrefix = entryPrefix || '-';
 
@@ -116,6 +116,10 @@ exports = module.exports = function transform(content, mode, maxHeaderLevel, tit
   var lines = content.split('\n')
     , info = updateSection.parse(lines, matchesStart, matchesEnd)
 
+  if (!info.hasStart && updateOnly) {
+    return { transformed: false };
+  }
+
   var inferredTitle = determineTitle(title, notitle, lines, info);
 
   var currentToc = info.hasStart && lines.slice(info.startIdx, info.endIdx + 1).join('\n')