docs: improve `ipfs add --help` (#10926)
* fix(cmds): improve ipfs add --help clarity and organization - clarify --raw-leaves behavior with CIDv0/v1 defaults - add Import.* config references to all relevant options - replace deprecated 'ipfs object links' with 'ipfs ls' in examples - add section headers for better navigation (BASIC EXAMPLES, MFS INTEGRATION, etc.) - group related options logically (output control, CID & hashing, experimental features) - standardize experimental warnings format - add MerkleDAG docs link and clarify chunking behavior - fix incorrect Import.UnixFSHAMTThreshold reference addresses confusion from #10918 where --raw-leaves appeared to have no effect because CIDv1 automatically enables it by default * docs: fix typos in Import.* configuration documentation - fix 'chilcren' → 'children' - fix 'HAMT directory have' → 'HAMT directories have' - fix 'A HAMT is an structure' → 'A HAMT is a structure' * Update core/commands/add.go Co-authored-by: Daniel Norman <1992255+2color@users.noreply.github.com> --------- Co-authored-by: Daniel Norman <1992255+2color@users.noreply.github.com>
Marcin Rataj committed
Aug 21, 2025 at 14:57 UTC
426477ef781e35491892a06050e287d0e76370ea
2 files changed
+47
-28
core/commands/add.go
+44
-25
@@ -76,13 +76,15 @@ Adds the content of <path> to IPFS. Use -r to add directories (recursively).
76
`,
77
LongDescription: `
78
Adds the content of <path> to IPFS. Use -r to add directories.
79
-Note that directories are added recursively, to form the IPFS
80
-MerkleDAG.
79
+Note that directories are added recursively, and big files are chunked,
80
+to form the IPFS MerkleDAG. Learn more: https://docs.ipfs.tech/concepts/merkle-dag/
81
82
-If the daemon is not running, it will just add locally.
82
+If the daemon is not running, it will just add locally to the repo at $IPFS_PATH.
83
If the daemon is started later, it will be advertised after a few
84
seconds when the reprovider runs.
85
86
+BASIC EXAMPLES:
87
+
88
The wrap option, '-w', wraps the file (or files, if using the
89
recursive option) in a directory. This directory contains only
90
the files which have been added, and means that the file retains
@@ -101,6 +103,12 @@ You can now refer to the added file in a gateway, like so:
103
Files imported with 'ipfs add' are protected from GC (implicit '--pin=true'),
104
but it is up to you to remember the returned CID to get the data back later.
105
106
+If you need to back up or transport content-addressed data using a non-IPFS
107
+medium, CID can be preserved with CAR files.
108
+See 'dag export' and 'dag import' for more information.
109
+
110
+MFS INTEGRATION:
111
+
112
Passing '--to-files' creates a reference in Files API (MFS), making it easier
113
to find it in the future:
114
@@ -112,6 +120,8 @@ to find it in the future:
120
See 'ipfs files --help' to learn more about using MFS
121
for keeping track of added files and directories.
122
123
+CHUNKING EXAMPLES:
124
+
125
The chunker option, '-s', specifies the chunking strategy that dictates
126
how to break files into blocks. Blocks with same content can
127
be deduplicated. Different chunking strategies will produce different
@@ -132,14 +142,16 @@ want to use a 1024 times larger chunk sizes for most files.
142
143
You can now check what blocks have been created by:
144
135
- > ipfs object links QmafrLBfzRLV4XSH1XcaMMeaXEUhDJjmtDfsYU95TrWG87
145
+ > ipfs ls QmafrLBfzRLV4XSH1XcaMMeaXEUhDJjmtDfsYU95TrWG87
146
QmY6yj1GsermExDXoosVE3aSPxdMNYr6aKuw3nA8LoWPRS 2059
147
Qmf7ZQeSxq2fJVJbCmgTrLLVN9tDR9Wy5k75DxQKuz5Gyt 1195
138
- > ipfs object links Qmf1hDN65tR55Ubh2RN1FPxr69xq3giVBz1KApsresY8Gn
148
+ > ipfs ls Qmf1hDN65tR55Ubh2RN1FPxr69xq3giVBz1KApsresY8Gn
149
QmY6yj1GsermExDXoosVE3aSPxdMNYr6aKuw3nA8LoWPRS 2059
150
QmerURi9k4XzKCaaPbsK6BL5pMEjF7PGphjDvkkjDtsVf3 868
151
QmQB28iwSriSUSMqG2nXDTLtdPHgWb4rebBrU7Q1j4vxPv 338
152
153
+ADVANCED CONFIGURATION:
154
+
155
Finally, a note on hash (CID) determinism and 'ipfs add' command.
156
157
Almost all the flags provided by this command will change the final CID, and
@@ -147,12 +159,11 @@ new flags may be added in the future. It is not guaranteed for the implicit
159
defaults of 'ipfs add' to remain the same in future Kubo releases, or for other
160
IPFS software to use the same import parameters as Kubo.
161
162
+Note: CIDv1 is automatically used when using non-default options like custom
163
+hash functions or when raw-leaves is explicitly enabled.
164
+
165
Use Import.* configuration options to override global implicit defaults:
166
https://github.com/ipfs/kubo/blob/master/docs/config.md#import
152
-
153
-If you need to back up or transport content-addressed data using a non-IPFS
154
-medium, CID can be preserved with CAR files.
155
-See 'dag export' and 'dag import' for more information.
167
`,
168
},
169
@@ -160,37 +171,45 @@ See 'dag export' and 'dag import' for more information.
171
cmds.FileArg("path", true, true, "The path to a file to be added to IPFS.").EnableRecursive().EnableStdin(),
172
},
173
Options: []cmds.Option{
174
+ // Input Processing
175
cmds.OptionRecursivePath, // a builtin option that allows recursive paths (-r, --recursive)
176
cmds.OptionDerefArgs, // a builtin option that resolves passed in filesystem links (--dereference-args)
177
cmds.OptionStdinName, // a builtin option that optionally allows wrapping stdin into a named file
178
cmds.OptionHidden,
179
cmds.OptionIgnore,
180
cmds.OptionIgnoreRules,
181
+ // Output Control
182
cmds.BoolOption(quietOptionName, "q", "Write minimal output."),
183
cmds.BoolOption(quieterOptionName, "Q", "Write only final hash."),
184
cmds.BoolOption(silentOptionName, "Write no output."),
185
cmds.BoolOption(progressOptionName, "p", "Stream progress data."),
173
- cmds.BoolOption(trickleOptionName, "t", "Use trickle-dag format for dag generation."),
186
+ // Basic Add Behavior
187
cmds.BoolOption(onlyHashOptionName, "n", "Only chunk and hash - do not write to disk."),
188
cmds.BoolOption(wrapOptionName, "w", "Wrap files with a directory object."),
176
- cmds.StringOption(chunkerOptionName, "s", "Chunking algorithm, size-[bytes], rabin-[min]-[avg]-[max] or buzhash. Default: Import.UnixFSChunker"),
177
- cmds.BoolOption(rawLeavesOptionName, "Use raw blocks for leaf nodes. Default: Import.UnixFSRawLeaves"),
178
- cmds.IntOption(maxFileLinksOptionName, "Limit the maximum number of links in UnixFS file nodes to this value. (experimental) Default: Import.UnixFSFileMaxLinks"),
179
- cmds.IntOption(maxDirectoryLinksOptionName, "Limit the maximum number of links in UnixFS basic directory nodes to this value. Default: Import.UnixFSDirectoryMaxLinks. WARNING: experimental, Import.UnixFSHAMTThreshold is a safer alternative."),
180
- cmds.IntOption(maxHAMTFanoutOptionName, "Limit the maximum number of links of a UnixFS HAMT directory node to this (power of 2, multiple of 8). Default: Import.UnixFSHAMTDirectoryMaxFanout WARNING: experimental, see Import.UnixFSHAMTDirectorySizeThreshold as well."),
181
- cmds.BoolOption(noCopyOptionName, "Add the file using filestore. Implies raw-leaves. (experimental)"),
182
- cmds.BoolOption(fstoreCacheOptionName, "Check the filestore for pre-existing blocks. (experimental)"),
183
- cmds.IntOption(cidVersionOptionName, "CID version. Defaults to 0 unless an option that depends on CIDv1 is passed. Passing version 1 will cause the raw-leaves option to default to true. Default: Import.CidVersion"),
184
- cmds.StringOption(hashOptionName, "Hash function to use. Implies CIDv1 if not sha2-256. Default: Import.HashFunction"),
185
- cmds.BoolOption(inlineOptionName, "Inline small blocks into CIDs. (experimental)"),
186
- cmds.IntOption(inlineLimitOptionName, "Maximum block size to inline. (experimental)").WithDefault(32),
189
cmds.BoolOption(pinOptionName, "Pin locally to protect added files from garbage collection.").WithDefault(true),
190
cmds.StringOption(pinNameOptionName, "Name to use for the pin. Requires explicit value (e.g., --pin-name=myname)."),
191
+ // MFS Integration
192
cmds.StringOption(toFilesOptionName, "Add reference to Files API (MFS) at the provided path."),
190
- cmds.BoolOption(preserveModeOptionName, "Apply existing POSIX permissions to created UnixFS entries. Disables raw-leaves. (experimental)"),
191
- cmds.BoolOption(preserveMtimeOptionName, "Apply existing POSIX modification time to created UnixFS entries. Disables raw-leaves. (experimental)"),
192
- cmds.UintOption(modeOptionName, "Custom POSIX file mode to store in created UnixFS entries. Disables raw-leaves. (experimental)"),
193
- cmds.Int64Option(mtimeOptionName, "Custom POSIX modification time to store in created UnixFS entries (seconds before or after the Unix Epoch). Disables raw-leaves. (experimental)"),
193
+ // CID & Hashing
194
+ cmds.IntOption(cidVersionOptionName, "CID version (0 or 1). CIDv1 automatically enables raw-leaves and is required for non-sha2-256 hashes. Default: Import.CidVersion"),
195
+ cmds.StringOption(hashOptionName, "Hash function to use. Implies CIDv1 if not sha2-256. Default: Import.HashFunction"),
196
+ cmds.BoolOption(rawLeavesOptionName, "Use raw blocks for leaf nodes. Note: CIDv1 automatically enables raw-leaves. Default: false for CIDv0, true for CIDv1 (Import.UnixFSRawLeaves)"),
197
+ // Chunking & DAG Structure
198
+ cmds.StringOption(chunkerOptionName, "s", "Chunking algorithm, size-[bytes], rabin-[min]-[avg]-[max] or buzhash. Files larger than chunk size are split into multiple blocks. Default: Import.UnixFSChunker"),
199
+ cmds.BoolOption(trickleOptionName, "t", "Use trickle-dag format for dag generation."),
200
+ // Advanced UnixFS Limits
201
+ cmds.IntOption(maxFileLinksOptionName, "Limit the maximum number of links in UnixFS file nodes to this value. WARNING: experimental. Default: Import.UnixFSFileMaxLinks"),
202
+ cmds.IntOption(maxDirectoryLinksOptionName, "Limit the maximum number of links in UnixFS basic directory nodes to this value. WARNING: experimental, Import.UnixFSHAMTDirectorySizeThreshold is safer. Default: Import.UnixFSDirectoryMaxLinks"),
203
+ cmds.IntOption(maxHAMTFanoutOptionName, "Limit the maximum number of links of a UnixFS HAMT directory node to this (power of 2, multiple of 8). WARNING: experimental, Import.UnixFSHAMTDirectorySizeThreshold is safer. Default: Import.UnixFSHAMTDirectoryMaxFanout"),
204
+ // Experimental Features
205
+ cmds.BoolOption(inlineOptionName, "Inline small blocks into CIDs. WARNING: experimental"),
206
+ cmds.IntOption(inlineLimitOptionName, "Maximum block size to inline. WARNING: experimental").WithDefault(32),
207
+ cmds.BoolOption(noCopyOptionName, "Add the file using filestore. Implies raw-leaves. WARNING: experimental"),
208
+ cmds.BoolOption(fstoreCacheOptionName, "Check the filestore for pre-existing blocks. WARNING: experimental"),
209
+ cmds.BoolOption(preserveModeOptionName, "Apply existing POSIX permissions to created UnixFS entries. WARNING: experimental, forces dag-pb for root block, disables raw-leaves"),
210
+ cmds.BoolOption(preserveMtimeOptionName, "Apply existing POSIX modification time to created UnixFS entries. WARNING: experimental, forces dag-pb for root block, disables raw-leaves"),
211
+ cmds.UintOption(modeOptionName, "Custom POSIX file mode to store in created UnixFS entries. WARNING: experimental, forces dag-pb for root block, disables raw-leaves"),
212
+ cmds.Int64Option(mtimeOptionName, "Custom POSIX modification time to store in created UnixFS entries (seconds before or after the Unix Epoch). WARNING: experimental, forces dag-pb for root block, disables raw-leaves"),
213
cmds.UintOption(mtimeNsecsOptionName, "Custom POSIX modification time (optional time fraction in nanoseconds)"),
214
},
215
PreRun: func(req *cmds.Request, env cmds.Environment) error {
docs/config.md
+3
-3
@@ -3194,7 +3194,7 @@ have when building the DAG while importing.
3194
This setting controls both the fanout for basic, non-HAMT folder nodes. It
3195
sets a limit after which directories are converted to a HAMT-based structure.
3196
3197
-When unset (0), no limit exists for chilcren. Directories will be converted to
3197
+When unset (0), no limit exists for children. Directories will be converted to
3198
HAMTs based on their estimated size only.
3199
3200
This setting will cause basic directories to be converted to HAMTs when they
@@ -3212,8 +3212,8 @@ Type: `optionalInteger`
3212
The maximum number of children that a node part of a Unixfs HAMT directory
3213
(aka sharded directory) can have.
3214
3215
-HAMT directory have unlimited children and are used when basic directories
3216
-become too big or reach `MaxLinks`. A HAMT is an structure made of unixfs
3215
+HAMT directories have unlimited children and are used when basic directories
3216
+become too big or reach `MaxLinks`. A HAMT is a structure made of unixfs
3217
nodes that store the list of elements in the folder. This option controls the
3218
maximum number of children that the HAMT nodes can have.
3219