docs(changelong): mode/mtime cli example

ipfs · Aug 13, 2024 · 89de255 · 89de255
1 parent fe20ae9
commit 89de255
Show file tree

Hide file tree

Showing 2 changed files with 29 additions and 6 deletions.
diff --git a/core/commands/files.go b/core/commands/files.go
@@ -1434,7 +1434,7 @@ The mode argument must be specified in Unix numeric notation.
 
 var filesTouchCmd = &cmds.Command{
 	Helptext: cmds.HelpText{
-		Tagline: "Change optional POSIX modification times.",
+		Tagline: "Set or change optional POSIX modification times.",
 		ShortDescription: `
 Examples:
     # set modification time to now.

diff --git a/docs/changelogs/v0.30.md b/docs/changelogs/v0.30.md
@@ -10,7 +10,7 @@
   - [AutoNAT V2 Service Introduced Alongside V1](#autonat-v2-service-introduced-alongside-v1)
   - [Automated `ipfs version check`](#automated-ipfs-version-check)
   - [Version Suffix Configuration](#version-suffix-configuration)
-  - [Unixfs Mode and Modification Time support](#mode-and-modification-time-support)
+  - [UnixFS 1.5: Mode and Modification Time Support](#unixfs-15-mode-and-modification-time-support)
 - [📝 Changelog](#-changelog)
 - [👨‍👩‍👧‍👦 Contributors](#-contributors)
 
@@ -47,13 +47,36 @@ If more than 5% of Kubo peers seen by your node are running a newer version, you
 
 Defining the optional agent version suffix is now simpler. The [`Version.AgentSuffix`](https://github.com/ipfs/kubo/blob/master/docs/config.md#agentsuffix) value from the Kubo config takes precedence over any value provided via `ipfs daemon --agent-version-suffix` (which is still supported).
 
-#### Mode and Modification Time Support
-
-Kubo lets a user opt-in to storing a mode and modification time on files, directories, and symbolic links. When adding file without mode and modification time, the same CIDs are generated that would have been created before this feature. Automatically updating a modification time will only occur if a modification time was previously stored.
-
 > [!NOTE]
 > Setting a custom version suffix helps with ecosystem analysis, such as Amino DHT reports published at https://stats.ipfs.network
 
+#### UnixFS 1.5: Mode and Modification Time Support
+
+Kubo now allows users to opt-in to store mode and modification time for files, directories, and symbolic links.
+By default, if you do not opt-in, the old behavior remains unchanged, and the same CIDs will be generated as before.
+
+The `ipfs add` CLI options `--preserve-mode` and `--preserve-mtime` can be used to store the original mode and last modified time of the file being added, and `ipfs files stat /ipfs/CID` can be used for inspecting these optional attributes:
+
+```console
+$ touch ./file
+$ chmod 654 ./file
+$ ipfs add --preserve-mode --preserve-mtime -Q ./file
+QmczQr4XS1rRnWVopyg5Chr9EQ7JKpbhgnrjpb5kTQ1DKQ
+
+$ ipfs files stat /ipfs/QmczQr4XS1rRnWVopyg5Chr9EQ7JKpbhgnrjpb5kTQ1DKQ
+QmczQr4XS1rRnWVopyg5Chr9EQ7JKpbhgnrjpb5kTQ1DKQ
+Size: 0
+CumulativeSize: 22
+ChildBlocks: 0
+Type: file
+Mode: -rw-r-xr-- (0654)
+Mtime: 13 Aug 2024, 21:15:31 UTC
+```
+
+The CLI and HTTP RPC options `--mode`, `--mtime` and `--mtime-nsecs` can be used to set them to arbitrary values.
+
+Opt-in support for `mode` and `mtime` was also added to MFS (`ipfs files --help`). For more information see `--help` text of `ipfs files touch|stat|chmod` commands.
+
 ### 📝 Changelog
 
 ### 👨‍👩‍👧‍👦 Contributors