git-sync-js

Documentation Site

JS implementation for Git-Sync, a handy script that backup your notes in a git repo to the remote git services.

Used by OpenSource free bi-link second brain note taking & knowledge map app TidGi-Desktop, refactor out to be a npm package.

npm i git-sync-js

Major Functions

There are three major functions: initGit, clone, commitAndSync, but you may import other helper functions and Error types, and GitStep types:

import {
  initGit,
  clone,
  commitAndSync,
  AssumeSyncError,
  CantSyncGitNotInitializedError,
  CantSyncInSpecialGitStateAutoFixFailed,
  getModifiedFileList,
  getRemoteUrl,
  GitPullPushError,
  GitStep,
  ILoggerContext,
  ModifiedFileList,
  SyncParameterMissingError,
  SyncScriptIsInDeadLoopError,
} from 'git-sync-js';

See api docs for full list of them.

You can see TidGi-Desktop's usage for full example.

initGit

initGit() Initialize a new .git on a folder. If set syncImmediately to true, it will push local git to remote immediately after init, you should provide userInfo.accessToken and remoteUrl, otherwise they are optional.

try {
  await initGit({
    dir: wikiFolderPath,
    remoteUrl,
    syncImmediately: isSyncedWiki,
    userInfo: { ...defaultGitInfo, ...userInfo },
    logger: {
      log: (message: string, context: ILoggerContext): unknown =>
        logger.info(message, { callerFunction: 'initWikiGit', ...context }),
      warn: (message: string, context: ILoggerContext): unknown =>
        logger.warn(message, { callerFunction: 'initWikiGit', ...context }),
      info: (message: GitStep, context: ILoggerContext): void => {
        logger.notice(this.translateMessage(message), {
          handler: WikiChannel.syncProgress,
          callerFunction: 'initWikiGit',
          ...context,
        });
      },
    },
  });
} catch (error) {
  this.translateErrorMessage(error);
}

commitAndSync

commitAndSync() is the Core feature of git-sync, commit all unstaged files, and try rebase on remote, and push to the remote.

try {
  await commitAndSync({
    dir: wikiFolderPath,
    remoteUrl,
    userInfo: { ...defaultGitInfo, ...userInfo },
    logger: {
      log: (message: string, context: ILoggerContext): unknown =>
        logger.info(message, { callerFunction: 'commitAndSync', ...context }),
      warn: (message: string, context: ILoggerContext): unknown =>
        logger.warn(message, { callerFunction: 'commitAndSync', ...context }),
      info: (message: GitStep, context: ILoggerContext): void => {
        logger.notice(this.translateMessage(message), {
          handler: WikiChannel.syncProgress,
          callerFunction: 'commitAndSync',
          ...context,
        });
      },
    },
    filesToIgnore,
  });
} catch (error) {
  this.translateErrorMessage(error);
}

clone

clone() will Clone a remote repo to a local location.

try {
  await clone({
    dir: repoFolderPath,
    remoteUrl,
    userInfo: { ...defaultGitInfo, ...userInfo },
    logger: {
      log: (message: string, context: ILoggerContext): unknown =>
        logger.info(message, { callerFunction: 'clone', ...context }),
      warn: (message: string, context: ILoggerContext): unknown =>
        logger.warn(message, { callerFunction: 'clone', ...context }),
      info: (message: GitStep, context: ILoggerContext): void => {
        logger.notice(this.translateMessage(message), {
          handler: WikiChannel.syncProgress,
          callerFunction: 'clone',
          ...context,
        });
      },
    },
  });
} catch (error) {
  this.translateErrorMessage(error);
}

Inspect helpers

getModifiedFileList

Get modified files and modify type in a folder

await getModifiedFileList(wikiFolderPath);

getDefaultBranchName

getSyncState

assumeSync

getGitRepositoryState

getGitDirectory

hasGit

Check if dir has .git.

Sync helpers

commitFiles

continueRebase

Steps

These is a git sync steps enum GitStep, that will log to logger when steps happened. You can write switch case on them in your custom logger, and translate them into user readable info.

StartGitInitialization
PrepareCloneOnlineWiki
GitRepositoryConfigurationFinished
StartConfiguringGithubRemoteRepository
StartBackupToGitRemote
PrepareSync
HaveThingsToCommit
AddingFiles
AddComplete
CommitComplete
PreparingUserInfo
FetchingData
NoNeedToSync
LocalAheadStartUpload
CheckingLocalSyncState
CheckingLocalGitRepoSanity
LocalStateBehindSync
LocalStateDivergeRebase
RebaseResultChecking
RebaseConflictNeedsResolve
RebaseSucceed
GitPushFailed
GitMergeFailed
SyncFailedAlgorithmWrong
PerformLastCheckBeforeSynchronizationFinish
SynchronizationFinish
StartFetchingFromGithubRemote
CantSyncInSpecialGitStateAutoFixSucceed

Errors

These are the errors like AssumeSyncError that will throw on git sync gets into fatal situations. You can try catch on major functions to get these errors, and instanceof these error to translate their message for user to read and report.

AssumeSyncError
SyncParameterMissingError
GitPullPushError
CantSyncGitNotInitializedError
SyncScriptIsInDeadLoopError
CantSyncInSpecialGitStateAutoFixFailed