feat: Added 'isIgnored' command (#1413)

.gitignore

@@ -102,6 +102,7 @@ docs/hashBlob.md
 docs/indexPack.md
 docs/init.md
 docs/isDescendent.md
+docs/isIgnored.md
 docs/listBranches.md
 docs/listFiles.md
 docs/listNotes.md

README.md

@@ -168,6 +168,7 @@ unless there is a major version bump.
 - [indexPack](https://isomorphic-git.github.io/docs/indexPack.html)
 - [init](https://isomorphic-git.github.io/docs/init.html)
 - [isDescendent](https://isomorphic-git.github.io/docs/isDescendent.html)
+- [isIgnored](https://isomorphic-git.github.io/docs/isIgnored.html)
 - [listBranches](https://isomorphic-git.github.io/docs/listBranches.html)
 - [listFiles](https://isomorphic-git.github.io/docs/listFiles.html)
 - [listNotes](https://isomorphic-git.github.io/docs/listNotes.html)

__tests__/test-exports.js

@@ -38,6 +38,7 @@ describe('exports', () => {
         "indexPack",
         "init",
         "isDescendent",
+        "isIgnored",
         "listBranches",
         "listFiles",
         "listNotes",

docs/alphabetic.md

@@ -31,6 +31,7 @@ sidebar_label: Alphabetical Index
 - [indexPack](indexPack)
 - [init](init)
 - [isDescendent](isDescendent)
+- [isIgnored](isIgnored)
 - [listBranches](listBranches)
 - [listFiles](listFiles)
 - [listNotes](listNotes)

src/api/isIgnored.js

@@ -0,0 +1,46 @@
+// @ts-check
+import '../typedefs.js'
+
+import { GitIgnoreManager } from '../managers/GitIgnoreManager.js'
+import { FileSystem } from '../models/FileSystem.js'
+import { assertParameter } from '../utils/assertParameter.js'
+import { join } from '../utils/join.js'
+
+/**
+ * Test whether a filepath should be ignored (because of .gitignore or .git/exclude)
+ *
+ * @param {object} args
+ * @param {FsClient} args.fs - a file system client
+ * @param {string} args.dir - The [working tree](dir-vs-gitdir.md) directory path
+ * @param {string} [args.gitdir=join(dir, '.git')] - [required] The [git directory](dir-vs-gitdir.md) path
+ * @param {string} args.filepath - The filepath to test
+ *
+ * @returns {Promise<boolean>} Resolves to true if the file should be ignored
+ *
+ * @example
+ * await git.isIgnored({ fs, dir: '/tutorial', filepath: 'docs/add.md' })
+ *
+ */
+export async function isIgnored({
+  fs,
+  dir,
+  gitdir = join(dir, '.git'),
+  filepath,
+}) {
+  try {
+    assertParameter('fs', fs)
+    assertParameter('dir', dir)
+    assertParameter('gitdir', gitdir)
+    assertParameter('filepath', filepath)
+
+    return GitIgnoreManager.isIgnored({
+      fs: new FileSystem(fs),
+      dir,
+      gitdir,
+      filepath,
+    })
+  } catch (err) {
+    err.caller = 'git.isIgnored'
+    throw err
+  }
+}

src/index.js

@@ -30,6 +30,7 @@ import { hashBlob } from './api/hashBlob.js'
 import { indexPack } from './api/indexPack.js'
 import { init } from './api/init.js'
 import { isDescendent } from './api/isDescendent.js'
+import { isIgnored } from './api/isIgnored.js'
 import { listBranches } from './api/listBranches.js'
 import { listFiles } from './api/listFiles.js'
 import { listNotes } from './api/listNotes.js'
@@ -100,6 +101,7 @@ export {
   indexPack,
   init,
   isDescendent,
+  isIgnored,
   listBranches,
   listFiles,
   listNotes,
@@ -169,6 +171,7 @@ export default {
   indexPack,
   init,
   isDescendent,
+  isIgnored,
   listBranches,
   listFiles,
   listNotes,

website/sidebars.json

@@ -50,7 +50,8 @@
       "add",
       "remove",
       "listFiles",
-      "status"
+      "status",
+      "isIgnored"
     ],
     "Notes": [
       "addNote",

website/versioned_docs/version-1.x/alphabetic.md

@@ -33,6 +33,7 @@ original_id: alphabetic
 - [indexPack](indexPack)
 - [init](init)
 - [isDescendent](isDescendent)
+- [isIgnored](isIgnored)
 - [listBranches](listBranches)
 - [listFiles](listFiles)
 - [listNotes](listNotes)

website/versioned_docs/version-1.x/isIgnored.md

@@ -0,0 +1,44 @@
+---
+title: isIgnored
+sidebar_label: isIgnored
+id: version-1.x-isIgnored
+original_id: isIgnored
+---
+
+Test whether a filepath should be ignored (because of .gitignore or .git/exclude)
+
+| param          | type [= default]           | description                                         |
+| -------------- | -------------------------- | --------------------------------------------------- |
+| [**fs**](./fs) | FsClient                   | a file system client                                |
+| **dir**        | string                     | The [working tree](dir-vs-gitdir.md) directory path |
+| **gitdir**     | string = join(dir, '.git') | The [git directory](dir-vs-gitdir.md) path          |
+| **filepath**   | string                     | The filepath to test                                |
+| return         | Promise\<boolean\>         | Resolves to true if the file should be ignored      |
+
+Example Code:
+
+```js live
+await git.isIgnored({ fs, dir: '/tutorial', filepath: 'docs/add.md' })
+```
+
+
+---
+
+<details>
+<summary><i>Tip: If you need a clean slate, expand and run this snippet to clean up the file system.</i></summary>
+
+```js live
+window.fs = new LightningFS('fs', { wipe: true })
+window.pfs = window.fs.promises
+console.log('done')
+```
+</details>
+
+<script>
+(function rewriteEditLink() {
+  const el = document.querySelector('a.edit-page-link.button');
+  if (el) {
+    el.href = 'https://github.com/isomorphic-git/isomorphic-git/edit/main/src/api/isIgnored.js';
+  }
+})();
+</script>

website/versioned_sidebars/version-1.x-sidebars.json

@@ -50,7 +50,8 @@
       "version-1.x-add",
       "version-1.x-remove",
       "version-1.x-listFiles",
-      "version-1.x-status"
+      "version-1.x-status",
+      "version-1.x-isIgnored"
     ],
     "Notes": [
       "version-1.x-addNote",