The docsync library, 0.1.7: every comment on a line is read, one directive per comment, and a second directive inside one comment is reported (directive.ErrSecondDirective); a ds:claim about= is measured against its own per-def baseline that only an ack moves, so a scan no longer clears an expired claim, claims about another repository's blocks expire, and a claim about a deleted, mistyped or newly defined block is flagged (check.AboutBaseline). To install the tool, see ds/v0.1.9.

go get github.com/ubgo/[email protected]

See CHANGELOG.md.

ds 0.1.9: every directive on a line is read, a ds:claim about= stays expired until someone renews it, and a workspace index missing on this machine no longer stops every command. Fixes issues 5, 6, 7 and 8. If you use about= claims, read Upgrading in the changelog first.

What changed

• Every directive on a line is read. A second <!-- ds:block … --> on the same line, beside a sentence, or in the next cell of a table row, was dropped without a word; each comment is now read, one directive per comment, and each table cell keeps its own sentence (bug 144). Two directives inside one comment now say so plainly: a second directive in one comment is not read; put each directive in its own comment (bug 148).
• Claims keep their baseline until renewed. A ds:claim about= is measured against the blocks as they were at its last renewal, as a citation is, so ds scan no longer clears an expired claim (bug 145). Claims about another workspace repository's blocks now expire, live and under check --frozen, and ds sync records their ids in .ds/foreign.tsv (bug 146). A claim about a deleted or mistyped id is broken (bug 149), and a new definition of its id, such as another env=, expires it until renewed (bug 152). A renewal records the blocks one by one, so a body-only edit to a stability=api block after a renewal is no longer reported.
• A missing workspace index warns instead of stopping everything. When the index is not on this machine, every command except ds sync and ds publish warns and reads other repositories' blocks from the committed .ds/foreign.tsv. Without that file such citations are reported broken, never passed, and ds check --strict exits 1. ds doctor shows WARN with foreign.tsv and FAIL without (bug 147).
• Clearer workspace and file errors. ds doctor shows git's real reason for an unreachable index (bug 150); a workspace path that does not exist, or a symlink to a missing folder, is named as a path, not cloned, and a bare host/path index is cloned over https (bug 151); an unreadable index entry or foreign.tsv warns instead of stopping every command or being ignored (bugs 153, 154); ds sync replaces a corrupt snapshot (bug 155); and a damaged .ds/*.tsv file comes with what to do about it (bug 156).

To update: ds update (or wait for the daily automatic update). Full list in the changelog; the decisions and their reasons are in SPEC §36.

Install

macOS (Apple silicon) and Linux (amd64, arm64):

curl -fsSL https://raw.githubusercontent.com/ubgo/docsync/main/install.sh | sh

Windows (amd64, ARM64), in PowerShell:

irm https://raw.githubusercontent.com/ubgo/docsync/main/install.ps1 | iex

With Go 1.26+ and a C compiler:

go install github.com/ubgo/docsync/cli/cmd/[email protected]

Every archive holds ds and the six secret-resolver plugins, with a checksums.txt.

The docsync cli module, 0.1.9: a workspace index missing on this machine warns and falls back to .ds/foreign.tsv instead of stopping every command, check --strict fails when foreign citations could not be checked, ds sync records claim ids and replaces a corrupt snapshot, and damaged .ds files come with a remedy. It requires the library at v0.1.7. To install the tool, see ds/v0.1.9.

go get github.com/ubgo/docsync/[email protected]

See CHANGELOG.md.

The docsync library, 0.1.6: check reports a bad lines= and a secret block-position cite for what they are instead of stale (new check.Options.RepoMode), System.FencesReport returns a note for every copy refresh skips or writes with only a link and follows [include] mode, scan drops directives that are data or damage in formats with no comment syntax (scan.CitesNothing), the config, markdown and document tiers report a bare ds:def line, and extract.ScanLinks exposes the one link grammar to tiers outside the package. To install the tool, see ds/v0.1.8.

go get github.com/ubgo/[email protected]

See CHANGELOG.md.

The docsync ext/structured module, 0.1.2, part of the 0.1.8 release: the YAML, TOML and HCL tiers read a link-form directive inside a comment (# see [8081](ds:cfg?id=…)) as a citation, as every other tier does. Values are not read for links. It requires the library at v0.1.6. To install the tool, see ds/v0.1.8.

go get github.com/ubgo/docsync/ext/[email protected]

See CHANGELOG.md.

ds 0.1.8: copies ds refresh cannot write are reported instead of staying stale forever, and directives are read only where they are real. Fixes issue 4.

What changed

• A lines= range that does not fit its block is reported as what it is. In repo mode, a ds:block whose lines= ran past the end of the block (or was not a range, such as lines=abc) was reported stale with "run ds refresh" as the fix, forever: refresh skipped the copy without saying why, and ds ack did not clear it. ds check now reports it as range, an error where the page owes a copy, with "adjust lines=" as the fix (bug 136).
• ds refresh never skips a copy silently. It names each copy it could not write, and why, and each copy it wrote with only its caption and link:

  $ ds refresh
  0 repo-mode copies rewritten
  skipped doc.md:3: lines=1-46 is outside the block's 45 lines
  1 repo-mode copies skipped
  0 moved; ledger updated
  

  --dry-run prints the same. The library has System.FencesReport for the same notes.
• The same class, fixed with it. A copy citing env=prod was rendered from another environment's def and stayed stale (bug 137). A ds:block of a secret, which never renders, stayed stale; it is now a problem naming a carrier that works (bug 138). In build mode, a copy already in a page was compared but never refreshed; ds refresh now keeps it current and adds none (bug 141).
• Directives are read only where they are real (SPEC "Reading directives" is now a table). A ds: link inside a JSON string or CSV cell is data, not a citation (bug 139). A whole-line ds:block outside a comment in JSON, CSV, go.sum, .gitignore and similar files is reported as damage instead of read as a citation (bug 140). A link inside a YAML, TOML or HCL comment is now a citation, as in every other comment (bug 142). A bare ds:def line in INI, env, HTML, Markdown and AsciiDoc files is now reported, as it already was in code (bug 143). A link inside a string literal in code is a citation, because strings hold prose; a whole-line directive in a string is not.

To update: ds update (or wait for the daily automatic update). Full list in the changelog; the decisions and their reasons are in SPEC §36.

Install

macOS (Apple silicon) and Linux (amd64, arm64):

curl -fsSL https://raw.githubusercontent.com/ubgo/docsync/main/install.sh | sh

Windows (amd64, ARM64), in PowerShell:

irm https://raw.githubusercontent.com/ubgo/docsync/main/install.ps1 | iex

With Go 1.26+ and a C compiler:

go install github.com/ubgo/docsync/cli/cmd/[email protected]

Every archive holds ds and the six secret-resolver plugins, with a checksums.txt.

The docsync cli module, 0.1.8: ds refresh names every copy it skips or writes with only a link, refreshes copies already in a page in build mode, and the language server drops directives that are data or damage, as a scan does. It requires the library at v0.1.6 and ext/structured at v0.1.2. To install the tool, see ds/v0.1.8.

go get github.com/ubgo/docsync/[email protected]

See CHANGELOG.md.

The docsync library, 0.1.5: the config gains an [update] table with mode (auto, notify, off; config.UpdateModeValues), which the ds CLI reads to decide whether a release build updates itself. The library itself never contacts the network. To install the tool, see ds/v0.1.7.

go get github.com/ubgo/[email protected]

See CHANGELOG.md.

ds 0.1.7: ds update, and a release build that keeps itself current.

What changed

• ds update installs the newest release of ds and the six resolver plugins beside it. The archive is checked against the release's checksums.txt before anything is replaced.

  $ ds update
  Current version: v0.1.6
  Checking for updates to latest version...
  ↑ Updating ds v0.1.6 → v0.1.7
  ✓ Downloaded and verified ds_v0.1.7_darwin_arm64.tar.gz  (14.8 MB, sha256 matches checksums.txt)
  ✓ Installed ds and 6 plugins in /usr/local/bin
  ✓ ds is now v0.1.7  what changed: https://github.com/ubgo/docsync/releases/tag/ds/v0.1.7
  Automatic updates: auto (default) · change with DS_UPDATE=notify|off or [update] mode in .ds/config.toml
  

  --check or --dry-run only reports, --version vX.Y.Z installs a named release (also to go back), --force reinstalls, --json prints the result. A go install or development build is told how it is updated instead.
• Automatic updates. At most once a day, before a command run at a terminal, ds checks for a newer release (waiting at most two seconds), installs it, and runs your command on it. It never does so in CI, under --json, when output is piped, or before doctor, lsp and mcp. A failed check is silent; a failed install is one warning and your command runs on the version you have.
• Turning it down: DS_UPDATE=notify (only say a release exists) or DS_UPDATE=off in your shell profile, --no-update for one run, or [update] mode = "notify" / "off" in .ds/config.toml for a whole team. The strictest setting wins. ds --help now lists the environment variables, and ds doctor has an update row with the mode, what set it and the last check.

This is the first release that can update itself: from 0.1.6, run the installer once more (or go install …@v0.1.7); after that, ds update and the daily check take over. Full list in the changelog; details in the guide.

Install

macOS (Apple silicon) and Linux (amd64, arm64):

curl -fsSL https://raw.githubusercontent.com/ubgo/docsync/main/install.sh | sh

Windows (amd64, ARM64), in PowerShell:

irm https://raw.githubusercontent.com/ubgo/docsync/main/install.ps1 | iex

With Go 1.26+ and a C compiler:

go install github.com/ubgo/docsync/cli/cmd/[email protected]

Every archive holds ds and the six secret-resolver plugins, with a checksums.txt.

The docsync cli module, 0.1.7: ds update, automatic updates for release builds, and the cli/selfupdate package (find, verify and install a release; no docsync dependency). It requires the library at v0.1.5. To install the tool, see ds/v0.1.7.

go get github.com/ubgo/docsync/[email protected]

See CHANGELOG.md.