From 1a0b17b920fe2aab67ab23d6027b198502e03ac0 Mon Sep 17 00:00:00 2001
From: bmacnaughton <bmacnaughton@gmail.com>
Date: Wed, 6 Dec 2023 08:54:31 -0800
Subject: [PATCH] update README

---
 README.md | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 9b55f16..f8f007f 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 ![commit-test](https://github.com/bmacnaughton/action-walk/workflows/commit-test/badge.svg)
 
-Minimal utility to walk directory trees performing actions on each directory
+Framework to walk directory trees performing actions on each directory
 entry. `action-walk` has no external production dependencies and has only one
 strong opinion - don't presume anything about why the directory tree is being
 walked.
@@ -11,9 +11,15 @@ No presumptions means that this does little more than walk the tree. There
 are two options to facilitate implementing your code on top of `action-walk`.
 If the boolean option `stat` is truthy `action-walk` will execute `fs.stat`
 on the entry and pass that to you action handler. If the option `own` is
-present `action-walk` will pass that to the action functions in a context
+present `action-walk` will pass it to the action functions in a context
 object.
 
+There is one additional option `includeTopLevel`. By default, `action-walk` does
+not call the action functions on the directory passed to `action-walk`; it just
+starts walking that directory. If `includeTopLevel` is truthy, `action-walk` will
+call the directory action function on the top level directory. This likely should
+have been the default but it's not as it's a breaking change.
+
 ### usage
 
 `action-walk` should run on any version of node that supports the `node:` prefix
@@ -43,7 +49,7 @@ function fileAction (path, context) {
   own.total += stat.size;
 }
 
-const own = {total: 0, skipDirs: ['node_modules']};
+const own = {total: 0, skipDirs: ['node_modules', '.git']};
 const options = {
   dirAction,
   fileAction,
@@ -57,7 +63,7 @@ walk('.', options)
   });
 
 // executed in the action-walk package root it will print something like
-// total bytes in "." 14778
+// total bytes in "." 109558
 ```
 
 see `test/basics.test.js` or `bin/walk.js` for other examples.
@@ -75,12 +81,13 @@ recurse into the directory.
 - `stat` - if `'lstat'` call `fs.lstat` on the entry and add it to the action context as
 the `stat` property. if otherwise truthy use `fs.stat`.
 - `own` - add this to the action context. it is your context for the action functions.
+- `includeTopLevel` - if truthy, the first call to `dirAction` will be for the the directory argument. if falsey, the first call to `dirAction` will be for the first entry in the directory.
 
 It's possible to call `walk()` with no options but probably not useful unless
 all you're wanting to do is seed the disk cache with directory entries. The
 action functions are where task-specific work is done.
 
-Each of the action function (`dirAction`, `fileAction`, `linkAction`, `otherAction`) is
+Each of the action functions (`dirAction`, `fileAction`, `linkAction`, `otherAction`) is
 called with two arguments:
 - `filepath` for the entry starting with `directory`, e.g., if `directory` is `test` and
 the entry is `basics.test.js` then `filepath` will be `test/basics.test.js`.