feat: add isIgnored command

__tests__/test-exports.js

@@ -38,6 +38,7 @@ describe('exports', () => {
         "indexPack",
         "init",
         "isDescendent",
+        "isIgnored",
         "listBranches",
         "listFiles",
         "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/getRemoteInfo.md

@@ -25,10 +25,11 @@ The object returned has the following schema:
 type GetRemoteInfoResult = {
   capabilities: Array<string>; // The list of capabilities returned by the server (part of the Git protocol)
   refs: {
-    heads: Object<string, string>; // The branches on the remote
-    pull: Object<string, string>; // The special branches representing pull requests (non-standard)
-    tags: Object<string, string>; // The tags on the remote
   };
+  HEAD?: string; // The default branch of the remote
+  refs.heads?: Object<string, string>; // The branches on the remote
+  refs.pull?: Object<string, string>; // The special branches representing pull requests (non-standard)
+  refs.tags?: Object<string, string>; // The tags on the remote
 }
 ```
 

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

@@ -7,16 +7,19 @@ original_id: log
 
 Get commit descriptions from the git history
 
-| 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                                                          |
-| ref            | string = 'HEAD'                      | The commit to begin walking backwards through the history from                                      |
-| depth          | number                               | Limit the number of commits returned. No limit by default.                                          |
-| since          | Date                                 | Return history newer than the given date. Can be combined with `depth` to get whichever is shorter. |
-| cache          | object                               | a [cache](cache.md) object                                                                          |
-| return         | Promise\<Array\<ReadCommitResult\>\> | Resolves to an array of ReadCommitResult objects                                                    |
+| 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                               | optional get the commit for the filepath only                                                           |
+| ref            | string = 'HEAD'                      | The commit to begin walking backwards through the history from                                          |
+| depth          | number                               | Limit the number of commits returned. No limit by default.                                              |
+| since          | Date                                 | Return history newer than the given date. Can be combined with `depth` to get whichever is shorter.     |
+| force          | boolean = false                      | do not throw error if filepath is not exist (works only for a single file). defaults to false           |
+| follow         | boolean = false                      | Continue listing the history of a file beyond renames (works only for a single file). defaults to false |
+| cache          | object                               | a [cache](cache.md) object                                                                              |
+| return         | Promise\<Array\<ReadCommitResult\>\> | Resolves to an array of ReadCommitResult objects                                                        |
 
 ```ts
 type ReadCommitResult = {

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

@@ -166,7 +166,7 @@ type Stat = {
 
 
 ```ts
-type WalkerMap = (filename: string, entries: Array<WalkerEntry>) => Promise<any>;
+type WalkerMap = (filename: string, entries: Array<(WalkerEntry|null)>) => Promise<any>;
 ```