{"id":15283849,"url":"https://github.com/tiddly-gittly/git-sync-js","last_synced_at":"2025-11-17T16:05:47.512Z","repository":{"id":47460898,"uuid":"363583052","full_name":"tiddly-gittly/git-sync-js","owner":"tiddly-gittly","description":"JS implementation for Git-Sync, a script that backup notes in git repo to the remote.","archived":false,"fork":false,"pushed_at":"2024-01-07T04:36:39.000Z","size":872,"stargazers_count":20,"open_issues_count":6,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-03T14:09:38.381Z","etag":null,"topics":["backup","backup-script","git","git-sync","note-taking","obsidian","sync","tiddlywiki"],"latest_commit_sha":null,"homepage":"https://tiddly-gittly.github.io/git-sync-js/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tiddly-gittly.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-02T06:30:08.000Z","updated_at":"2025-06-25T03:03:40.000Z","dependencies_parsed_at":"2025-02-11T15:43:57.387Z","dependency_job_id":null,"html_url":"https://github.com/tiddly-gittly/git-sync-js","commit_stats":null,"previous_names":["linonetwo/git-sync-js"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tiddly-gittly/git-sync-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiddly-gittly%2Fgit-sync-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiddly-gittly%2Fgit-sync-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiddly-gittly%2Fgit-sync-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiddly-gittly%2Fgit-sync-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tiddly-gittly","download_url":"https://codeload.github.com/tiddly-gittly/git-sync-js/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiddly-gittly%2Fgit-sync-js/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266904406,"owners_count":24004092,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-24T02:00:09.469Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backup","backup-script","git","git-sync","note-taking","obsidian","sync","tiddlywiki"],"created_at":"2024-09-30T14:47:59.963Z","updated_at":"2025-11-17T16:05:47.505Z","avatar_url":"https://github.com/tiddly-gittly.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# git-sync-js\n\n[Documentation Site](https://tiddly-gittly.github.io/git-sync-js/)\n\nJS implementation for [Git-Sync](https://github.com/simonthum/git-sync), a handy script that backup your notes in a git repo to the remote git services.\n\nUsed by OpenSource free bi-link second brain note taking \u0026 knowledge map app [TidGi-Desktop](https://github.com/tiddly-gittly/TidGi-Desktop), refactor out to be a npm package.\n\n```shell\nnpm i git-sync-js\n```\n\n## Major Functions\n\nThere are three major functions: `initGit, clone, commitAndSync`, but you may import other helper functions and Error types, and GitStep types:\n\n```ts\nimport {\n  AssumeSyncError,\n  CantSyncGitNotInitializedError,\n  CantSyncInSpecialGitStateAutoFixFailed,\n  clone,\n  commitAndSync,\n  getModifiedFileList,\n  getRemoteUrl,\n  GitPullPushError,\n  GitStep,\n  ILoggerContext,\n  initGit,\n  ModifiedFileList,\n  SyncParameterMissingError,\n  SyncScriptIsInDeadLoopError,\n} from 'git-sync-js';\n```\n\nSee [api docs](./docs/api/) for full list of them.\n\nYou can see [TidGi-Desktop's usage](https://github.com/tiddly-gittly/TidGi-Desktop/blob/9e73bbf96deb5a4c085bbf9c56dc38e62efdd550/src/services/git/gitWorker.ts) for full example.\n\n### initGit\n\n[initGit()](./docs/api/modules/initGit.md) 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.\n\n```ts\ntry {\n  await initGit({\n    dir: wikiFolderPath,\n    remoteUrl,\n    syncImmediately: isSyncedWiki,\n    userInfo: { ...defaultGitInfo, ...userInfo },\n    logger: {\n      log: (message: string, context: ILoggerContext): unknown =\u003e logger.info(message, { callerFunction: 'initWikiGit', ...context }),\n      warn: (message: string, context: ILoggerContext): unknown =\u003e logger.warn(message, { callerFunction: 'initWikiGit', ...context }),\n      info: (message: GitStep, context: ILoggerContext): void =\u003e {\n        logger.notice(this.translateMessage(message), {\n          handler: WikiChannel.syncProgress,\n          callerFunction: 'initWikiGit',\n          ...context,\n        });\n      },\n    },\n  });\n} catch (error) {\n  this.translateErrorMessage(error);\n}\n```\n\n### commitAndSync\n\n[commitAndSync()](./docs/api/modules/commitAndSync.md) is the Core feature of git-sync, commit all unstaged files, and try rebase on remote, and push to the remote.\n\n```ts\ntry {\n  await commitAndSync({\n    dir: wikiFolderPath,\n    remoteUrl,\n    userInfo: { ...defaultGitInfo, ...userInfo },\n    logger: {\n      log: (message: string, context: ILoggerContext): unknown =\u003e logger.info(message, { callerFunction: 'commitAndSync', ...context }),\n      warn: (message: string, context: ILoggerContext): unknown =\u003e logger.warn(message, { callerFunction: 'commitAndSync', ...context }),\n      info: (message: GitStep, context: ILoggerContext): void =\u003e {\n        logger.notice(this.translateMessage(message), {\n          handler: WikiChannel.syncProgress,\n          callerFunction: 'commitAndSync',\n          ...context,\n        });\n      },\n    },\n    filesToIgnore,\n  });\n} catch (error) {\n  this.translateErrorMessage(error);\n}\n```\n\n### clone\n\n[clone()](./docs/api/modules/clone.md) will Clone a remote repo to a local location.\n\n```ts\ntry {\n  await clone({\n    dir: repoFolderPath,\n    remoteUrl,\n    userInfo: { ...defaultGitInfo, ...userInfo },\n    logger: {\n      log: (message: string, context: ILoggerContext): unknown =\u003e logger.info(message, { callerFunction: 'clone', ...context }),\n      warn: (message: string, context: ILoggerContext): unknown =\u003e logger.warn(message, { callerFunction: 'clone', ...context }),\n      info: (message: GitStep, context: ILoggerContext): void =\u003e {\n        logger.notice(this.translateMessage(message), {\n          handler: WikiChannel.syncProgress,\n          callerFunction: 'clone',\n          ...context,\n        });\n      },\n    },\n  });\n} catch (error) {\n  this.translateErrorMessage(error);\n}\n```\n\n## Inspect helpers\n\n### getModifiedFileList\n\nGet modified files and modify type in a folder\n\n```ts\nawait getModifiedFileList(wikiFolderPath);\n```\n\n### getDefaultBranchName\n\n### getSyncState\n\n### assumeSync\n\n### getGitRepositoryState\n\n### getGitDirectory\n\n### hasGit\n\nCheck if dir has `.git`.\n\n## Sync helpers\n\n### commitFiles\n\n### continueRebase\n\n## Steps\n\nThese is a git sync steps enum [GitStep](./docs/api/enums/interface.GitStep.md), 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.\n\n```shell\nStartGitInitialization\nPrepareCloneOnlineWiki\nGitRepositoryConfigurationFinished\nStartConfiguringGithubRemoteRepository\nStartBackupToGitRemote\nPrepareSync\nHaveThingsToCommit\nAddingFiles\nAddComplete\nCommitComplete\nPreparingUserInfo\nFetchingData\nNoNeedToSync\nLocalAheadStartUpload\nCheckingLocalSyncState\nCheckingLocalGitRepoSanity\nLocalStateBehindSync\nLocalStateDivergeRebase\nRebaseResultChecking\nRebaseConflictNeedsResolve\nRebaseSucceed\nGitPushFailed\nGitMergeFailed\nSyncFailedAlgorithmWrong\nPerformLastCheckBeforeSynchronizationFinish\nSynchronizationFinish\nStartFetchingFromGithubRemote\nCantSyncInSpecialGitStateAutoFixSucceed\n```\n\n## Errors\n\nThese are the errors like [AssumeSyncError](./docs/api/classes/errors.AssumeSyncError.md) 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.\n\n```shell\nAssumeSyncError\nSyncParameterMissingError\nGitPullPushError\nCantSyncGitNotInitializedError\nSyncScriptIsInDeadLoopError\nCantSyncInSpecialGitStateAutoFixFailed\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiddly-gittly%2Fgit-sync-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftiddly-gittly%2Fgit-sync-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiddly-gittly%2Fgit-sync-js/lists"}