docs: add jsdoc and new error type

Author: linonetwo

src/clone.ts

@@ -8,6 +8,7 @@ import { getRemoteName } from './inspect';
 import { GitStep, IGitUserInfos, ILogger } from './interface';
 
 export async function clone(options: {
+  /** Optional fallback of userInfo. If some info is missing in userInfo, will use defaultGitInfo instead. */
   defaultGitInfo?: typeof defaultDefaultGitInfo;
   /** wiki folder path, can be relative, should exist before function call */
   dir: string;

src/commitAndSync.ts

@@ -10,6 +10,7 @@ export interface ICommitAndSyncOptions {
   /** the commit message */
   commitMessage?: string;
   commitOnly?: boolean;
+  /** Optional fallback of userInfo. If some info is missing in userInfo, will use defaultGitInfo instead. */
   defaultGitInfo?: typeof defaultDefaultGitInfo;
   /** wiki folder path, can be relative */
   dir: string;

src/errors.ts

@@ -90,3 +90,14 @@ export class CantSyncInSpecialGitStateAutoFixFailed extends Error {
       `E-6 Unable to Sync, this folder is in special condition, thus can't Sync directly. An auto-fix has been tried, but error still remains. Please resolve all the conflict manually (For example, use VSCode to open the wiki folder), if this still don't work out, please use professional Git tools (Source Tree, GitKraken) to solve this. This is caused by procedural bug in the git-sync-js.\n${stateMessage}`;
   }
 }
+
+export class CantForcePullError extends Error {
+  stateMessage: string;
+  constructor(stateMessage: string) {
+    super(stateMessage);
+    Object.setPrototypeOf(this, CantForcePullError.prototype);
+    this.stateMessage = stateMessage;
+    this.name = 'CantForcePullError';
+    this.message = `E-7 Unable to force pull remote. This is caused by procedural bug in the git-sync-js.\n${stateMessage}`;
+  }
+}

src/forcePull.ts

@@ -1,12 +1,13 @@
 import { GitProcess } from 'dugite';
 import { credentialOff, credentialOn } from './credential';
 import { defaultGitInfo as defaultDefaultGitInfo } from './defaultGitInfo';
-import { SyncParameterMissingError } from './errors';
+import { CantForcePullError, SyncParameterMissingError } from './errors';
 import { getDefaultBranchName, getRemoteName } from './inspect';
 import { GitStep, IGitUserInfos, ILogger } from './interface';
 import { fetchRemote } from './sync';
 
 export interface IForcePullOptions {
+  /** Optional fallback of userInfo. If some info is missing in userInfo, will use defaultGitInfo instead. */
   defaultGitInfo?: typeof defaultDefaultGitInfo;
   /** wiki folder path, can be relative */
   dir: string;
@@ -23,6 +24,7 @@ export interface IForcePullOptions {
 
 /**
  * Ignore all local changes, force reset local to remote.
+ * This is usually used in readonly blog, that will fetch content from a remote repo. And you can push content to the remote repo, let the blog update.
  */
 export async function forcePull(options: IForcePullOptions) {
   const { dir, logger, defaultGitInfo = defaultDefaultGitInfo, userInfo, remoteUrl } = options;
@@ -65,14 +67,23 @@ export async function forcePull(options: IForcePullOptions) {
     logProgress(GitStep.StartResettingLocalToRemote);
     await hardResetLocalToRemote(dir, branch, remoteName);
     logProgress(GitStep.FinishForcePull);
+  } catch (error) {
+    if (error instanceof CantForcePullError) {
+      throw error;
+    } else {
+      throw new CantForcePullError(`${(error as Error).message} ${(error as Error).stack ?? ''}`);
+    }
   } finally {
     await credentialOff(dir, remoteName, remoteUrl);
   }
 }
 
+/**
+ * Internal method used by forcePull, does the `reset --hard`.
+ */
 export async function hardResetLocalToRemote(dir: string, branch: string, remoteName: string) {
   const { exitCode, stderr } = await GitProcess.exec(['reset', '--hard', `${remoteName}/${branch}`], dir);
   if (exitCode !== 0) {
-    throw new Error(`Failed to reset local to remote: ${stderr}`);
+    throw new CantForcePullError(`${remoteName}/${branch} ${stderr}`);
   }
 }

src/index.ts

@@ -1,12 +1,12 @@
 /** primary functions */
 export * from './clone';
 export * from './commitAndSync';
+export * from './forcePull';
 export * from './initGit';
 /** utils */
 export * from './credential';
 export * from './defaultGitInfo';
 export * from './errors';
-export * from './forcePull';
 export * from './inspect';
 export * from './interface';
 export * from './sync';

src/initGit.ts

@@ -8,6 +8,7 @@ import { commitFiles } from './sync';
 
 export type IInitGitOptions = IInitGitOptionsSyncImmediately | IInitGitOptionsNotSync;
 export interface IInitGitOptionsSyncImmediately {
+  /** Optional fallback of userInfo. If some info is missing in userInfo, will use defaultGitInfo instead. */
   defaultGitInfo?: typeof defaultDefaultGitInfo;
   /** wiki folder path, can be relative */
   dir: string;