From 89de255345b44c1a5068a4b64df79022c7d7a2df Mon Sep 17 00:00:00 2001
From: Marcin Rataj <lidel@lidel.org>
Date: Tue, 13 Aug 2024 23:58:37 +0200
Subject: [PATCH] docs(changelong): mode/mtime cli example

---
 core/commands/files.go   |  2 +-
 docs/changelogs/v0.30.md | 33 ++++++++++++++++++++++++++++-----
 2 files changed, 29 insertions(+), 6 deletions(-)

diff --git a/core/commands/files.go b/core/commands/files.go
index 50f6ac1a15eb..304a1a1b18e6 100644
--- 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
index fee21e7ae803..60ff04c57615 100644
--- 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