Add gitignore support, enabled by default

Respect .gitignore files when listing directory trees inside a git
repository. Uses the `ignore` npm package to parse patterns. Finds the
git root, reads root and nested .gitignore files, and filters entries
before stat'ing for performance. Use --no-gitignore to disable.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: yangshun

README.md

@@ -11,7 +11,7 @@ Note: Symlinks are not followed. Directories that cannot be opened (e.g. due to
 Instantly execute the command in your current directory via `npx` / `pnpx` / `bunx` / `yarn dlx`:
 
 ```bash
-npx tree-node-cli -I "node_modules" # ignore node_modules
+npx tree-node-cli
 ```
 
 ## Installation
@@ -87,6 +87,8 @@ Options:
   --files-first             List files before directories.
   --sort <type>             Sort the output by type: name, version, mtime,
                             ctime, size.
+  --gitignore               Respect .gitignore files (enabled by default).
+                            Use --no-gitignore to disable.
   -h, --help                Display this message
   --version                 Display version number
 ```
@@ -158,6 +160,7 @@ console.log(result);
 | `dirsOnly`      | `false`                    | `boolean`  | List directories only.                                                                                                                                                                                                                                                                                |
 | `sizes`         | `false`                    | `boolean`  | Print the size of each file in bytes along with the name.                                                                                                                                                                                                                                             |
 | `du`            | `false`                    | `boolean`  | For each directory, report its size as the accumulation of sizes of all its files and sub-directories. Implies `sizes`.                                                                                                                                                                               |
+| `gitignore`     | `true`                     | `boolean`  | Respect `.gitignore` files when inside a git repository. Use `--no-gitignore` to disable.                                                                                                                                                                                                             |
 | `exclude`       | `[]`                       | `RegExp[]` | An array of regex to test each filename against. Matching files will be excluded and matching directories will not be traversed into. To exclude a directory's contents while still showing the directory itself, use a regex that matches the path with a trailing slash (e.g., `/node_modules\//`). |
 | `maxDepth`      | `Number.POSITIVE_INFINITY` | `number`   | Max display depth of the directory tree.                                                                                                                                                                                                                                                              |
 | `reverse`       | `false`                    | `boolean`  | Sort the output in reverse alphabetic order.                                                                                                                                                                                                                                                          |

package.json

@@ -49,6 +49,7 @@
   },
   "dependencies": {
     "cac": "^7.0.0",
+    "ignore": "^7.0.5",
     "pretty-bytes": "^7.1.0"
   },
   "devDependencies": {

pnpm-lock.yaml

@@ -1,8 +1,8 @@
-import { execFile } from 'child_process';
+import { execFile, execSync } from 'child_process';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
-import { describe, expect, test } from 'vitest';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
 
 const TSX_PATH = path.resolve(__dirname, '../node_modules/.bin/tsx');
 const CLI_PATH = path.resolve(__dirname, 'cli.ts');
@@ -361,4 +361,37 @@ describe('cli', () => {
     expect(withoutAll).not.toContain('.gitkeep');
     expect(withAll).toContain('.gitkeep');
   });
+
+  test('help includes --gitignore option', async () => {
+    const { stdout } = await run(['-h']);
+    expect(stdout).toContain('--gitignore');
+  });
+
+  describe('--no-gitignore', () => {
+    let tmpDir: string;
+
+    beforeEach(() => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tree-cli-gitignore-'));
+      execSync('git init', { cwd: tmpDir });
+      fs.writeFileSync(path.join(tmpDir, '.gitignore'), 'secret.txt\n');
+      fs.writeFileSync(path.join(tmpDir, 'secret.txt'), '');
+      fs.writeFileSync(path.join(tmpDir, 'visible.txt'), '');
+    });
+
+    afterEach(() => {
+      fs.rmSync(tmpDir, { recursive: true });
+    });
+
+    test('excludes gitignored files by default', async () => {
+      const { stdout } = await run([tmpDir]);
+      expect(stdout).not.toContain('secret.txt');
+      expect(stdout).toContain('visible.txt');
+    });
+
+    test('shows gitignored files with --no-gitignore', async () => {
+      const { stdout } = await run(['--no-gitignore', tmpDir]);
+      expect(stdout).toContain('secret.txt');
+      expect(stdout).toContain('visible.txt');
+    });
+  });
 });

src/cli.test.ts

@@ -50,6 +50,10 @@ cli
   .option(
     '--sort <type>',
     'Sort the output by type: name, version, mtime, ctime, size.',
+  )
+  .option(
+    '--gitignore',
+    'Respect .gitignore files (enabled by default). Use --no-gitignore to disable.',
   );
 
 cli.help();
@@ -105,6 +109,7 @@ const options: Options = {
   }),
   ...(opts.lineAscii != null && { lineAscii: opts.lineAscii as boolean }),
   ...(opts.unsorted != null && { unsorted: opts.unsorted as boolean }),
+  ...(opts.gitignore != null && { gitignore: opts.gitignore as boolean }),
 };
 
 if (opts.json) {

src/cli.ts

@@ -181,10 +181,7 @@ describe('formatAsText', () => {
       makeDir('forbidden', [], { path: 'root/forbidden', openError: true }),
     ]);
     const lines = formatAsText(node, opts({ trailingSlash: true }), '.');
-    expect(lines).toEqual([
-      'root/',
-      '└── forbidden/ [error opening dir]',
-    ]);
+    expect(lines).toEqual(['root/', '└── forbidden/ [error opening dir]']);
   });
 
   test('vertical line for non-last siblings', () => {

src/formats/text.test.ts

@@ -1,3 +1,4 @@
+import { execSync } from 'child_process';
 import fs from 'fs';
 import { isNotJunk } from 'junk';
 import os from 'os';
@@ -774,3 +775,80 @@ describe('tree with special characters in filenames', () => {
     expect(result).toContain('file-with-dashes.txt');
   });
 });
+
+describe('tree with gitignore', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tree-gitignore-'));
+    execSync('git init', { cwd: tmpDir });
+    fs.writeFileSync(
+      path.join(tmpDir, '.gitignore'),
+      'ignored-dir/\nignored-file.txt\n',
+    );
+    fs.mkdirSync(path.join(tmpDir, 'ignored-dir'));
+    fs.writeFileSync(path.join(tmpDir, 'ignored-dir', 'file.txt'), '');
+    fs.writeFileSync(path.join(tmpDir, 'ignored-file.txt'), '');
+    fs.writeFileSync(path.join(tmpDir, 'visible-file.txt'), '');
+    fs.mkdirSync(path.join(tmpDir, 'visible-dir'));
+    fs.writeFileSync(path.join(tmpDir, 'visible-dir', 'nested.txt'), '');
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  test('excludes gitignored files by default', () => {
+    const result = tree(tmpDir);
+    expect(result).not.toContain('ignored-dir');
+    expect(result).not.toContain('ignored-file.txt');
+    expect(result).toContain('visible-file.txt');
+    expect(result).toContain('visible-dir');
+  });
+
+  test('shows gitignored files when gitignore is false', () => {
+    const result = tree(tmpDir, { gitignore: false });
+    expect(result).toContain('ignored-dir');
+    expect(result).toContain('ignored-file.txt');
+    expect(result).toContain('visible-file.txt');
+  });
+
+  test('works with nested .gitignore', () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'visible-dir', '.gitignore'),
+      'nested.txt\n',
+    );
+    const result = tree(tmpDir, { allFiles: true });
+    expect(result).not.toContain('nested.txt');
+    expect(result).toContain('visible-dir');
+  });
+
+  test('gitignore has no effect outside git repo', () => {
+    const nonGitDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tree-nogit-'));
+    fs.writeFileSync(path.join(nonGitDir, '.gitignore'), '*.txt\n');
+    fs.writeFileSync(path.join(nonGitDir, 'file.txt'), '');
+
+    const result = tree(nonGitDir);
+    expect(result).toContain('file.txt');
+
+    fs.rmSync(nonGitDir, { recursive: true });
+  });
+
+  test('gitignore works together with exclude option', () => {
+    const result = tree(tmpDir, { exclude: [/visible-dir/] });
+    expect(result).not.toContain('ignored-dir');
+    expect(result).not.toContain('ignored-file.txt');
+    expect(result).not.toContain('visible-dir');
+    expect(result).toContain('visible-file.txt');
+  });
+
+  test('gitignore works with treeJson', () => {
+    const result = treeJson(tmpDir);
+    const dir = asDir(result);
+    const names = dir.contents.map((c) => c.name);
+    expect(names).not.toContain('ignored-dir');
+    expect(names).not.toContain('ignored-file.txt');
+    expect(names).toContain('visible-file.txt');
+    expect(names).toContain('visible-dir');
+  });
+});

src/index.test.ts

@@ -3,6 +3,11 @@ import nodePath from 'path';
 
 import { type TreeJsonEntry, formatAsJson } from './formats/json';
 import { formatAsText } from './formats/text';
+import {
+  type GitignoreFilter,
+  createGitignoreFilter,
+  findGitRoot,
+} from './utils/gitignore';
 
 export type SortBy = 'name' | 'version' | 'mtime' | 'ctime' | 'size';
 
@@ -25,6 +30,7 @@ export interface Options {
   sortBy?: SortBy;
   trailingSlash?: boolean;
   lineAscii?: boolean;
+  gitignore?: boolean;
   unsorted?: boolean;
 }
 
@@ -44,6 +50,7 @@ const DEFAULT_OPTIONS: RequiredOptions = {
   quote: false,
   sizes: false,
   exclude: [],
+  gitignore: true,
   maxDepth: Number.POSITIVE_INFINITY,
   reverse: false,
   sortBy: 'name',
@@ -67,6 +74,14 @@ export interface TreeNode {
   openError?: boolean;
 }
 
+// ── Build context ─────────────────────────────────────────
+
+interface BuildContext {
+  sizeCache: Map<string, number>;
+  gitignoreFilter: GitignoreFilter | null;
+  gitRoot: string | null;
+}
+
 // ── Build tree ─────────────────────────────────────────────
 
 /**
@@ -196,6 +211,7 @@ function filterAndOrderContents(
 function getDirectoryContents(
   dirPath: string,
   options: RequiredOptions,
+  ctx: BuildContext,
 ): { entries: string[]; stats: Map<string, fs.Stats>; openError: boolean } {
   let entries: string[];
 
@@ -210,8 +226,37 @@ function getDirectoryContents(
     entries = entries.filter((entry) => !isHiddenFile(entry));
   }
 
+  // Load nested .gitignore and filter ignored entries before stat'ing.
+  if (ctx.gitignoreFilter && ctx.gitRoot) {
+    const absDirPath = nodePath.resolve(dirPath);
+    ctx.gitignoreFilter.loadNestedGitignore(absDirPath);
+    entries = entries.filter((entry) => {
+      const relPath = nodePath.relative(
+        ctx.gitRoot!,
+        nodePath.join(absDirPath, entry),
+      );
+      return !ctx.gitignoreFilter!.ignores(relPath, false);
+    });
+  }
+
   const { stats, accessible } = statEntries(dirPath, entries);
-  const sorted = sortContentsInPlace(accessible, stats, options);
+
+  // Secondary gitignore check for directory-only patterns (e.g. "logs/").
+  let finalAccessible = accessible;
+  if (ctx.gitignoreFilter && ctx.gitRoot) {
+    const absDirPath = nodePath.resolve(dirPath);
+    finalAccessible = accessible.filter((entry) => {
+      const stat = stats.get(entry);
+      if (!stat?.isDirectory()) return true;
+      const relPath = nodePath.relative(
+        ctx.gitRoot!,
+        nodePath.join(absDirPath, entry),
+      );
+      return !ctx.gitignoreFilter!.ignores(relPath, true);
+    });
+  }
+
+  const sorted = sortContentsInPlace(finalAccessible, stats, options);
   const filtered = filterAndOrderContents(sorted, stats, options);
 
   return { entries: filtered, stats, openError: false };
@@ -269,7 +314,7 @@ function buildTree(
   path: string,
   currentDepth: number,
   options: RequiredOptions,
-  sizeCache: Map<string, number>,
+  ctx: BuildContext,
   cachedStat?: fs.Stats,
 ): TreeNode | null {
   const stat = cachedStat ?? fs.lstatSync(path);
@@ -286,15 +331,19 @@ function buildTree(
     isDirectory: isDir,
     mode: stat.mode,
     mtime: stat.mtime,
-    size: sizeCache.get(path) ?? stat.size,
+    size: ctx.sizeCache.get(path) ?? stat.size,
     children: [],
   };
 
   if (isFile || currentDepth >= options.maxDepth) {
     return node;
   }
 
-  const { entries, stats, openError } = getDirectoryContents(path, options);
+  const { entries, stats, openError } = getDirectoryContents(
+    path,
+    options,
+    ctx,
+  );
 
   if (openError) {
     node.openError = true;
@@ -306,7 +355,7 @@ function buildTree(
       nodePath.join(path, entry),
       currentDepth + 1,
       options,
-      sizeCache,
+      ctx,
       stats.get(entry),
     );
 
@@ -337,10 +386,21 @@ function buildTreeNode(
     computeSizes(path, sizeCache);
   }
 
-  const resolvedPath = nodePath.join(process.cwd(), path);
+  const resolvedPath = nodePath.resolve(path);
   const rootName = nodePath.basename(resolvedPath);
 
-  return buildTree(rootName, path, 0, options, sizeCache);
+  let gitignoreFilter: GitignoreFilter | null = null;
+  let gitRoot: string | null = null;
+  if (options.gitignore) {
+    gitRoot = findGitRoot(resolvedPath);
+    if (gitRoot) {
+      gitignoreFilter = createGitignoreFilter(gitRoot);
+    }
+  }
+
+  const ctx: BuildContext = { sizeCache, gitignoreFilter, gitRoot };
+
+  return buildTree(rootName, path, 0, options, ctx);
 }
 
 /**