@cryptotaxi247 / kubo / commits / af0dcf631

docs: copyedit v0.41 release notes and touched docs

Marcin Rataj committed Apr 23, 2026 at 23:05 UTC af0dcf63123a5cbd9b26c13264e425e58cadff06

5 files changed +33 -34

docs/RELEASE_CHECKLIST.md

+4 -4

@@ -26,20 +26,20 @@

26 - [ ] Verify all CI checks on the PR are passing

27 - [ ] **FINAL only:** Replace `Changelog` and `Contributors` sections in `release-vX.Y.Z` with `./bin/mkreleaselog` stdout (do **NOT** copy stderr)

28 - [ ] **FINAL only:** Merge PR (`release-vX.Y.Z` → `release`) using `Create a merge commit`

29 - - ⚠️ do **NOT** use `Squash and merge` nor `Rebase and merge` -- we want the releaser's GPG signature on the merge commit

29 + - ⚠️ do **NOT** use `Squash and merge` nor `Rebase and merge`; we want the releaser's GPG signature on the merge commit

30 - ⚠️ do **NOT** delete the `release-vX.Y.Z` branch (needed for future patch releases and git history)

32 ## 2. Tag & Publish

34 ### Create Tag

35 -⚠️ **POINT OF NO RETURN:** Once pushed, tags trigger automatic Docker/NPM publishing and are irreversible!

35 +⚠️ **POINT OF NO RETURN:** once pushed, tags trigger automatic Docker/NPM publishing that cannot be undone!

36 If you're making a release for the first time, do pair programming and have the release reviewer verify all commands.

38 - [ ] **RC:** From `release-vX.Y.Z` branch: `git tag -s vX.Y.Z-rcN -m 'Prerelease X.Y.Z-rcN'`

39 - [ ] **FINAL:** After PR merge, from `release` branch: `git tag -s vX.Y.Z -m 'Release X.Y.Z'`

40 - [ ] ⚠️ Verify tag is signed and correct: `git show vX.Y.Z(-rcN)`

41 - [ ] Push tag: `git push origin vX.Y.Z(-rcN)`

42 - - ⚠️ do **NOT** use `git push --tags` (pushes all local tags, polluting the repo with noise)

42 + - ⚠️ do **NOT** use `git push --tags` (pushes every local tag, cluttering the repo)

43 - [ ] **STOP:** Wait for [Docker build](https://github.com/ipfs/kubo/actions/workflows/docker-image.yml) to complete before proceeding

45 ### Publish Artifacts

@@ -77,7 +77,7 @@ If you're making a release for the first time, do pair programming and have the

77 - [ ] Merge `master` to `merge-release-vX.Y.Z` first, and resolve conflict in `version.go`

78 - ⚠️ **NOTE:** keep the `-dev` version from `master` in [version.go](https://github.com/ipfs/kubo/blob/master/version.go), discard version from `release`

79 - [ ] Create and merge PR from `merge-release-vX.Y.Z` to `master` using `Create a merge commit`

80 - - ⚠️ do **NOT** use `Squash and merge` nor `Rebase and merge` -- only `Create a merge commit` preserves commit history and audit trail of what was merged where

80 + - ⚠️ do **NOT** use `Squash and merge` nor `Rebase and merge`; only `Create a merge commit` preserves commit history and the audit trail of what was merged where

81 - [ ] Update [ipshipyard/waterworks-infra](https://github.com/ipshipyard/waterworks-infra)

82 - [ ] Update Kubo staging environment ([Running Kubo tests on staging](https://www.notion.so/Running-Kubo-tests-on-staging-488578bb46154f9bad982e4205621af8))

83 - [ ] **RC:** Test last release against current RC

docs/changelogs/v0.41.md

+9 -9

@@ -114,7 +114,7 @@ Nodes using custom routing (`Routing.Type=custom`) with [IPIP-526](https://githu

114 Experimental opt-in optimizations for content providers with large repositories where multiple recursive pins share most of their DAG structure (e.g. append-only datasets, versioned archives like dist.ipfs.tech).

115

116 - `+unique`: bloom filter dedup across recursive pins. Shared subtrees are traversed only once per reprovide cycle instead of once per pin, cutting I/O from O(pins * blocks) to O(unique blocks) at ~4 bytes/CID.

117 -- `+entities`: announces only entity roots (files, directories, HAMT shards), skipping internal file chunks. Drastically fewer DHT provider records while keeping all content discoverable by file/directory CID. Implies `+unique`.

117 +- `+entities`: announces only entity roots (files, directories, HAMT shards), skipping internal file chunks. Far fewer DHT provider records while keeping all content discoverable by file/directory CID. Implies `+unique`.

118

119 Example: `Provide.Strategy = "pinned+mfs+entities"`

120

@@ -139,7 +139,7 @@ Pass `--fast-provide-dag=true` (or set [`Import.FastProvideDAG`](https://github.

139 `Provide.Strategy=all` (default) is unaffected. It provides every block at the blockstore level regardless of this flag.

140

141 > [!NOTE]

142 -> **Faster default imports for `Provide.Strategy=pinned` and `pinned+mfs` users.** Previously, `ipfs add --pin` eagerly announced every block of newly added content as it was written, through an internal DAG service wrapper. This release consolidates add-time providing through the new `--fast-provide-dag` code path, which defaults to `false`. The out-of-the-box result is faster bulk imports and less provide traffic during add: only the root CID is announced immediately (via [`Import.FastProvideRoot`](https://github.com/ipfs/kubo/blob/master/docs/config.md#importfastprovideroot)), and child blocks are picked up by the next reprovide cycle (see [`Provide.DHT.Interval`](https://github.com/ipfs/kubo/blob/master/docs/config.md#providedhtinterval), default 22h). To restore the previous eager-provide behavior on `ipfs add`, set [`Import.FastProvideDAG=true`](https://github.com/ipfs/kubo/blob/master/docs/config.md#importfastprovidedag) (or pass `--fast-provide-dag=true` per command); the walker honors the active `Provide.Strategy`. `Provide.Strategy=all` (the default) is unaffected.

142 +> **Faster default imports for `Provide.Strategy=pinned` and `pinned+mfs` users.** Previously, `ipfs add --pin` eagerly announced every block of newly added content as it was written, through an internal DAG service wrapper. This release routes add-time providing through the new `--fast-provide-dag` code path, which defaults to `false`. The result is faster bulk imports and less provide traffic during add: only the root CID is announced immediately (via [`Import.FastProvideRoot`](https://github.com/ipfs/kubo/blob/master/docs/config.md#importfastprovideroot)), and child blocks are picked up by the next reprovide cycle (see [`Provide.DHT.Interval`](https://github.com/ipfs/kubo/blob/master/docs/config.md#providedhtinterval), default 22h). To restore the previous eager-provide behavior on `ipfs add`, set [`Import.FastProvideDAG=true`](https://github.com/ipfs/kubo/blob/master/docs/config.md#importfastprovidedag) (or pass `--fast-provide-dag=true` per command); the walker honors the active `Provide.Strategy`. `Provide.Strategy=all` (the default) is unaffected.

143

144 #### 🛡️ Hardened `Provide.Strategy` parsing

145

@@ -180,15 +180,15 @@ See [boxo#1125](https://github.com/ipfs/boxo/pull/1125) and [kubo#11273](https:/

180

181 #### 📂 FUSE Mount Improvements

182

183 -The FUSE implementation has been rewritten on top of [`hanwen/go-fuse` v2](https://github.com/hanwen/go-fuse), replacing the unmaintained `bazil.org/fuse`. This fixes long-standing architectural limitations and brings FUSE mounts much closer to what standard tools expect. FUSE support is still experimental. See [docs/fuse.md](https://github.com/ipfs/kubo/blob/master/docs/fuse.md) for setup instructions, and report problems at [kubo/issues](https://github.com/ipfs/kubo/issues).

183 +The FUSE implementation has been rewritten on top of [`hanwen/go-fuse` v2](https://github.com/hanwen/go-fuse), replacing the unmaintained `bazil.org/fuse`. This fixes long-standing architectural limitations and aligns FUSE mounts with what standard tools expect. FUSE support is still experimental. See [docs/fuse.md](https://github.com/ipfs/kubo/blob/master/docs/fuse.md) for setup instructions, and report problems at [kubo/issues](https://github.com/ipfs/kubo/issues).

184

185 - **`fsync` works.** Editors (vim, emacs) and databases that call `fsync` after writing no longer get a silent no-op. Data is flushed through the open file descriptor to the DAG. The full vim save sequence (O_TRUNC + write + fsync + chmod) is tested.

186 - **`ftruncate` works.** Tools like `rsync --inplace` that shrink or grow files via `ftruncate(fd, size)` no longer get ENOTSUP. Opening existing files with `O_TRUNC` also works correctly.

187 -- **`chmod` and `touch` no longer drop file content.** Setting mode or mtime on a file with `Mounts.StoreMode`/`StoreMtime` enabled previously replaced the DAG node without preserving content links, making the file appear empty.

187 +- **`chmod` and `touch` no longer drop file content.** With `Mounts.StoreMode`/`StoreMtime` enabled, setting mode or mtime previously replaced the DAG node without preserving content links, leaving the file empty.

188 - **Symlink creation on writable mounts.** `ln -s target link` now works on `/mfs` and `/ipns`. Symlinks are stored as UnixFS TSymlink nodes, the same format used by `ipfs add`.

189 - **Rename-over-existing works.** Renaming a file onto an existing name (the pattern used by rsync and atomic-save editors) now correctly replaces the target.

190 - **Faster reads on `/ipfs`.** Files are read sequentially from the block graph instead of re-resolving from the root on every read call.

191 -- **Killing a stuck `cat` works.** Interrupting a read (Ctrl-C, kill) cancels in-flight block fetches instead of hanging.

191 +- **Interrupting a stuck `cat` works.** Ctrl-C or `kill` on a read cancels in-flight block fetches instead of hanging.

192 - **External unmount detected.** Running `fusermount -u` from outside the daemon now correctly marks the mount as inactive.

193 - **Files are no longer owned by root.** Mounts report the uid/gid of the daemon process, so access works without `allow_other`.

194 - **Offline IPNS writes succeed.** IPNS records are stored locally and published when connectivity returns.

@@ -202,13 +202,13 @@ The FUSE implementation has been rewritten on top of [`hanwen/go-fuse` v2](https

202 - **UnixFS mode and mtime visible in stat.** All three mounts show POSIX mode and mtime from [UnixFS](https://specs.ipfs.tech/unixfs/) metadata when present. When absent, sensible POSIX defaults are used (files: `0644`/`0444`, directories: `0755`/`0555`).

203 - **Opt-in `Mounts.StoreMtime` and `Mounts.StoreMode`.** Writable mounts can persist mtime on file creation/write and POSIX mode on `chmod` for both files and directories. `touch` on directories also works, which tools like `tar` and `rsync` rely on. Both flags are off by default because they change the resulting CID. See [`Mounts.StoreMtime`](https://github.com/ipfs/kubo/blob/master/docs/config.md#mountsstoremtime) and [`Mounts.StoreMode`](https://github.com/ipfs/kubo/blob/master/docs/config.md#mountsstoremode).

204 - **`ipfs.cid` xattr on all mounts.** All three mounts expose the node's CID via the `ipfs.cid` extended attribute on files and directories. The legacy `ipfs_cid` xattr name (used in earlier versions of `/mfs`) is no longer supported; use `ipfs.cid` instead.

205 -- **`statfs` works.** All three mounts report the free space of the volume backing the local IPFS repo, so `/mfs` correctly reflects how much new data can be onboarded. Fixes macOS Finder refusing copies with "not enough free space".

205 +- **`statfs` works.** All three mounts report the free space of the volume backing the local IPFS repo, so `/mfs` correctly reflects how much new data fits. Fixes macOS Finder refusing copies with "not enough free space".

206 - **Per-entry `st_blocks` and `st_blksize` reflect UnixFS.** All three mounts fill `st_blocks` from the UnixFS file size so `du`, `ls -s`, `stat`, and "size on disk" in file managers match `ls -l`. Directories report a nominal 1 block so tools that treat 0 as "unsupported" behave correctly. `st_blksize` advertises a chunk-aligned preferred I/O size: `/mfs` and `/ipns` use [`Import.UnixFSChunker`](https://github.com/ipfs/kubo/blob/master/docs/config.md#importunixfschunker), so `cp`, `dd`, and `rsync` buffer writes at the chunker boundary; `/ipfs` uses a stable 1 MiB hint since published CIDs have no single chunker.

207 - **Platform compatibility.** macOS detection updated from OSXFUSE 2.x to macFUSE 4.x. Linux no longer needs a `fusermount` symlink; [`hanwen/go-fuse`](https://github.com/hanwen/go-fuse) finds `fusermount3` natively.

208

209 #### 📦 CARv2 import over HTTP API

210

211 -`ipfs dag import` of CARv2 files now works over the HTTP API. Previously it failed with `operation not supported` because the HTTP multipart stream falsely advertised seek support, which go-car relied on for CARv2 payload offset. See [#11253](https://github.com/ipfs/kubo/pull/11253).

211 +`ipfs dag import` of CARv2 files now works over the HTTP API. Previously it failed with `operation not supported`: the HTTP multipart stream falsely advertised seek support, which go-car needs for the CARv2 payload offset. See [#11253](https://github.com/ipfs/kubo/pull/11253).

212

213 #### 🌐 HTTPS proxy support

214

@@ -227,7 +227,7 @@ $ ipfs config profile apply server

227 The command is idempotent. See the [`server` profile docs](https://github.com/ipfs/kubo/blob/master/docs/config.md#server-profile) for the full filter list, RFC references, and override guidance.

228

229 > [!WARNING]

230 -> The `server` profile disables local peer discovery ([`Discovery.MDNS`](https://github.com/ipfs/kubo/blob/master/docs/config.md#discoverymdns) off, loopback filtered), so co-located daemons on the same host and peers on the same LAN will no longer find each other automatically. Apply only on public-internet nodes where that is the intended behavior.

230 +> The `server` profile disables local peer discovery ([`Discovery.MDNS`](https://github.com/ipfs/kubo/blob/master/docs/config.md#discoverymdns) off, loopback filtered), so co-located daemons on the same host and peers on the same LAN will no longer find each other automatically. Apply only on public-internet nodes where that is intended.

231

232 #### 🐹 Go 1.26, Once More with Feeling

233

@@ -241,7 +241,7 @@ Long-running daemons could exit with `invalid memory address or nil pointer dere

241

242 Two recent changes likely tipped the race into frequent visible crashes: [go-multiaddr v0.15](https://github.com/multiformats/go-multiaddr/releases/tag/v0.15.0) turned `Multiaddr` from an interface into a slice-backed struct, and [Go 1.26](https://go.dev/doc/go1.26) added heap base address randomization and a new garbage collector. Both likely made torn concurrent reads more likely to dereference unmapped memory.

243

244 -This release picks up the targeted fix in [go-libp2p-kad-dht#1244](https://github.com/libp2p/go-libp2p-kad-dht/pull/1244). A broader fix covering the whole class of routing publish races is proposed upstream in [go-libp2p#3490](https://github.com/libp2p/go-libp2p/pull/3490).

244 +This release picks up the targeted fix in [go-libp2p-kad-dht#1244](https://github.com/libp2p/go-libp2p-kad-dht/pull/1244). A broader fix for the whole class of routing publish races is proposed upstream in [go-libp2p#3490](https://github.com/libp2p/go-libp2p/pull/3490).

245

246 #### 📦️ Dependency updates

247

docs/config.md

+13 -13

@@ -2124,16 +2124,16 @@ Controls which CIDs are announced to the content routing system. Valid strategie

2124

2125 #### Strategy modifiers: `+unique` and `+entities`

2126

2127 -The `+unique` and `+entities` modifiers can be appended to `pinned`, `mfs`, or `pinned+mfs` strategies to optimize the reprovide cycle. They are incompatible with `"all"` and `"roots"`.

2128 -

2129 -- **`+unique`** -- uses a bloom filter to deduplicate CIDs across recursive

2130 - pins that share sub-DAGs. Without this, a node with 1000 pins that share 99%

2131 - of their content re-traverses the shared blocks for each pin. With `+unique`,

2132 - shared subtrees are detected and skipped, reducing traversal from

2133 - O(pins * total_blocks) to O(unique_blocks). This also significantly reduces

2134 - the amount of CIDs sent to the routing system when similar datasets are

2135 - pinned multiple times.

2136 -- **`+entities`** -- announces only entity roots (file roots, directory roots,

2127 +Append `+unique` or `+entities` to `pinned`, `mfs`, or `pinned+mfs` to optimize the reprovide cycle. Neither works with `"all"` or `"roots"`.

2128 +

2129 +- **`+unique`**: uses a bloom filter to deduplicate CIDs across recursive

2130 + pins that share sub-DAGs. Without it, a node with 1000 pins sharing 99%

2131 + of their content re-traverses the shared blocks for every pin. With `+unique`,

2132 + shared subtrees are skipped, cutting traversal from

2133 + O(pins * total_blocks) to O(unique_blocks). This also cuts the number of

2134 + CIDs sent to the routing system when similar datasets are pinned multiple

2135 + times.

2136 +- **`+entities`**: announces only entity roots (file roots, directory roots,

2137 HAMT shard nodes) instead of every block. Internal file chunks are not

2138 announced. This significantly reduces the number of provider records for

2139 repositories with large files while keeping all files and directories

@@ -2147,11 +2147,11 @@ The `+unique` and `+entities` modifiers can be appended to `pinned`, `mfs`, or `

2147

2148 **Suggested configurations:**

2149

2150 -- `"pinned+mfs+unique"` -- safe default for nodes with GC enabled, or desktop

2150 +- `"pinned+mfs+unique"`: safe default for nodes with GC enabled, or desktop

2151 users who don't want to announce all blocks cached in the local repository.

2152 Handles pins of similar DAGs efficiently (e.g. versioned datasets where pins

2153 are added and removed over time).

2154 -- `"pinned+mfs+entities"` -- same as above, but also skips internal file chunks

2154 +- `"pinned+mfs+entities"`: same as above, but also skips internal file chunks

2155 for even fewer provider records. Use when the `+entities` trade-off (no

2156 chunk-level discoverability) is acceptable.

2157

@@ -2559,7 +2559,7 @@ The minimum accepted value is `1000000` (1 in 1M). Below that the bloom

2559 filter becomes lossy enough to drop a meaningful fraction of CIDs from each

2560 reprovide cycle.

2561

2562 -Default: `4750000` (~1 false positive per 4.75M lookups, cost at ~4 bytes per CID)

2562 +Default: `4750000` (~1 false positive per 4.75M lookups, ~4 bytes per CID)

2563

2564 Type: `optionalInteger`

2565

docs/environment-variables.md

+3 -3

@@ -117,7 +117,7 @@ Warning: Enabling tracing will likely affect performance.

117

118 ## `IPFS_FUSE_DEBUG`

119

120 -When set to any non-empty value, enables verbose FUSE debug logging. Every FUSE operation (open, read, write, lookup, getattr, etc.) is logged to stderr with its arguments and return values. Useful for diagnosing mount issues or understanding what the kernel is requesting.

120 +When set to any non-empty value, logs every FUSE operation (open, read, write, lookup, getattr, etc.) to stderr with its arguments and return values. Useful for diagnosing mount issues or inspecting what the kernel requests.

121

122 Default: not set (no debug logging)

123

@@ -319,8 +319,8 @@ Default: [160](https://github.com/libp2p/go-libp2p/blob/master/p2p/net/swarm/swa

319 ## `TEST_DHT_STUB`

320

321 Lifts WAN DHT filters so kubo can operate against DHT peers on

322 -loopback, enabling full end-to-end provide/findprovs/IPNS testing

323 -without public internet access. All DHT code paths are exercised:

322 +loopback, enabling end-to-end provide/findprovs/IPNS testing

323 +without public internet access. Exercises every DHT code path:

324 dial, protocol negotiation, message serialization, routing table

325 management.

326

docs/fuse.md

+4 -5

@@ -2,8 +2,8 @@

3 **EXPERIMENTAL:** FUSE support is functional but still evolving. Please report issues at [kubo/issues](https://github.com/ipfs/kubo/issues).

5 -Kubo makes it possible to mount `/ipfs`, `/ipns` and `/mfs` namespaces in your OS,

6 -allowing arbitrary apps access to IPFS using standard filesystem operations.

5 +Kubo can mount `/ipfs`, `/ipns`, and `/mfs` namespaces in your OS,

6 +letting arbitrary apps access IPFS through standard filesystem operations.

8 The underlying FUSE implementation uses [`hanwen/go-fuse`](https://github.com/hanwen/go-fuse).

@@ -58,7 +58,7 @@ After installation, open **System Settings > Privacy & Security** and allow the

58 Kubo automatically sets `volname`, `noapplexattr`, and `noappledouble` mount options on macOS:

60 - `volname` shows the filesystem name (ipfs, ipns, mfs) in Finder instead of the generic "macfuse Volume 0"

61 -- `noapplexattr` prevents Finder from probing Apple-private extended attributes on every file access, reducing unnecessary FUSE traffic on network-backed mounts

61 +- `noapplexattr` stops Finder from probing Apple-private extended attributes on every file access, cutting FUSE traffic on network-backed mounts

62 - `noappledouble` prevents macOS from creating `._` resource fork sidecar files, which would pollute the DAG with macOS-only metadata

64 > [!NOTE]

@@ -150,8 +150,7 @@ ipfs.cid="bafkreifjjcie6lypi6ny7amxnfftagclbuxndqonfipmb64f2km2devei4"

150

151 ## Mode and mtime

152

153 -By default, IPFS does not persist POSIX file mode or modification time. Most content on IPFS

154 -does not include this metadata.

153 +By default, IPFS does not persist POSIX mode or mtime, and most content on IPFS omits this metadata.

154

155 When mode or mtime is absent, FUSE mounts use sensible defaults:

156