docs: deprecate object commands
Part of https://github.com/ipfs/go-ipfs/issues/7936 This PR makes it very explicit that 'ipfs object' are deprecated by removing examples and pointing at modern replacements under 'ipfs dag' and 'ipfs files' Taglines are longer and include alternatives because we use them on: https://docs.ipfs.io/reference/http/api/
Marcin Rataj committed
Apr 30, 2021 at 01:27 UTC
8c1e4e99d115f8481136b8c12293a58acdcc7872
4 files changed
+84
-72
README.md
-1
@@ -298,7 +298,6 @@ SUBCOMMANDS
298
DATA STRUCTURE COMMANDS
299
dag Interact with IPLD DAG nodes
300
files Interact with files as if they were a unix filesystem
301
- object Interact with dag-pb objects (deprecated, use 'dag' or 'files')
301
block Interact with raw blocks in the datastore
302
303
ADVANCED COMMANDS
core/commands/object/object.go
+45
-57
@@ -48,7 +48,7 @@ const (
48
49
var ObjectCmd = &cmds.Command{
50
Helptext: cmds.HelpText{
51
- Tagline: "Interact with dag-pb objects (deprecated, use generic 'dag')",
51
+ Tagline: "Deprecated commands to interact with dag-pb objects. Use 'dag' or 'files' instead.",
52
ShortDescription: `
53
'ipfs object' is a legacy plumbing command used to manipulate dag-pb objects
54
directly. Deprecated, use more modern 'ipfs dag' and 'ipfs files' instead.`,
@@ -69,14 +69,16 @@ directly. Deprecated, use more modern 'ipfs dag' and 'ipfs files' instead.`,
69
// ObjectDataCmd object data command
70
var ObjectDataCmd = &cmds.Command{
71
Helptext: cmds.HelpText{
72
- Tagline: "Output the raw bytes of a dag-pb object.",
72
+ Tagline: "Deprecated way to read the raw bytes of a dag-pb object: use 'dag get' instead.",
73
ShortDescription: `
74
-'ipfs object data' is a plumbing command for retrieving the raw bytes stored
75
-in a dag-pb node. It outputs to stdout, and <key> is a base58 encoded multihash.
74
+'ipfs object data' is a deprecated plumbing command for retrieving the raw
75
+bytes stored in a dag-pb node. It outputs to stdout, and <key> is a base58
76
+encoded multihash. Provided for legacy reasons. Use 'ipfs dag get' instead.
77
`,
78
LongDescription: `
78
-'ipfs object data' is a plumbing command for retrieving the raw bytes stored
79
-in a dag-pb node. It outputs to stdout, and <key> is a base58 encoded multihash.
79
+'ipfs object data' is a deprecated plumbing command for retrieving the raw
80
+bytes stored in a dag-pb node. It outputs to stdout, and <key> is a base58
81
+encoded multihash. Provided for legacy reasons. Use 'ipfs dag get' instead.
82
83
Note that the "--encoding" option does not affect the output, since the output
84
is the raw data of the object.
@@ -106,11 +108,11 @@ is the raw data of the object.
108
// ObjectLinksCmd object links command
109
var ObjectLinksCmd = &cmds.Command{
110
Helptext: cmds.HelpText{
109
- Tagline: "Output the links pointed to by the specified dag-pb object.",
111
+ Tagline: "Deprecated way to output links in the specified dag-pb object: use 'dag get' instead.",
112
ShortDescription: `
113
'ipfs object links' is a plumbing command for retrieving the links from
114
a dag-pb node. It outputs to stdout, and <key> is a base58 encoded
113
-multihash.
115
+multihash. Provided for legacy reasons. Use 'ipfs dag get' instead.
116
`,
117
},
118
@@ -180,29 +182,13 @@ multihash.
182
// ObjectGetCmd object get command
183
var ObjectGetCmd = &cmds.Command{
184
Helptext: cmds.HelpText{
183
- Tagline: "Get and serialize the dag-pb node named by <key>.",
185
+ Tagline: "Deprecated way to get and serialize the dag-pb node. Use 'dag get' instead",
186
ShortDescription: `
187
'ipfs object get' is a plumbing command for retrieving dag-pb nodes.
188
It serializes the DAG node to the format specified by the "--encoding"
189
flag. It outputs to stdout, and <key> is a base58 encoded multihash.
188
-`,
189
- LongDescription: `
190
-'ipfs object get' is a plumbing command for retrieving dag-pb nodes.
191
-It serializes the DAG node to the format specified by the "--encoding"
192
-flag. It outputs to stdout, and <key> is a base58 encoded multihash.
193
-
194
-This command outputs data in the following encodings:
195
- * "protobuf"
196
- * "json"
197
- * "xml"
198
-(Specified by the "--encoding" or "--enc" flag)
199
-
200
-The encoding of the object's data field can be specified by using the
201
---data-encoding flag
190
203
-Supported values are:
204
- * "text" (default)
205
- * "base64"
191
+DEPRECATED and provided for legacy reasons. Use 'ipfs dag get' instead.
192
`,
193
},
194
@@ -287,9 +273,15 @@ Supported values are:
273
// ObjectStatCmd object stat command
274
var ObjectStatCmd = &cmds.Command{
275
Helptext: cmds.HelpText{
290
- Tagline: "Get stats for the dag-pb node named by <key>.",
276
+ Tagline: "Deprecated way to read stats for the dag-pb node. Use 'files stat' instead.",
277
ShortDescription: `
278
'ipfs object stat' is a plumbing command to print dag-pb node statistics.
279
+<key> is a base58 encoded multihash.
280
+
281
+DEPRECATED: modern replacements are 'files stat' and 'dag stat'
282
+`,
283
+ LongDescription: `
284
+'ipfs object stat' is a plumbing command to print dag-pb node statistics.
285
<key> is a base58 encoded multihash. It outputs to stdout:
286
287
NumLinks int number of links in link table
@@ -297,6 +289,26 @@ var ObjectStatCmd = &cmds.Command{
289
LinksSize int size of the links segment
290
DataSize int size of the data segment
291
CumulativeSize int cumulative size of object and its references
292
+
293
+DEPRECATED: Provided for legacy reasons. Modern replacements:
294
+
295
+ For unixfs, 'ipfs files stat' can be used:
296
+
297
+ $ ipfs files stat --with-local /ipfs/QmWfVY9y3xjsixTgbd9AorQxH7VtMpzfx2HaWtsoUYecaX
298
+ QmWfVY9y3xjsixTgbd9AorQxH7VtMpzfx2HaWtsoUYecaX
299
+ Size: 5
300
+ CumulativeSize: 13
301
+ ChildBlocks: 0
302
+ Type: file
303
+ Local: 13 B of 13 B (100.00%)
304
+
305
+ Reported sizes are based on metadata present in root block, and should not be
306
+ trusted. A slower, but more secure alternative is 'ipfs dag stat', which
307
+ will work for every DAG type. It comes with a benefit of calculating the
308
+ size by walking the DAG:
309
+
310
+ $ ipfs dag stat /ipfs/QmWfVY9y3xjsixTgbd9AorQxH7VtMpzfx2HaWtsoUYecaX
311
+ Size: 13, NumBlocks: 1
312
`,
313
},
314
@@ -360,39 +372,12 @@ var ObjectStatCmd = &cmds.Command{
372
// ObjectPutCmd object put command
373
var ObjectPutCmd = &cmds.Command{
374
Helptext: cmds.HelpText{
363
- Tagline: "Store input as a dag-pb object, print its key.",
375
+ Tagline: "Deprecated way to store input as a DAG object. Use 'dag put' instead.",
376
ShortDescription: `
377
'ipfs object put' is a plumbing command for storing dag-pb nodes.
378
It reads from stdin, and the output is a base58 encoded multihash.
367
-`,
368
- LongDescription: `
369
-'ipfs object put' is a plumbing command for storing dag-pb nodes.
370
-It reads from stdin, and the output is a base58 encoded multihash.
371
-
372
-Data should be in the format specified by the --inputenc flag.
373
---inputenc may be one of the following:
374
- * "protobuf"
375
- * "json" (default)
379
377
-Examples:
378
-
379
- $ echo '{ "Data": "abc" }' | ipfs object put
380
-
381
-This creates a node with the data 'abc' and no links. For an object with
382
-links, create a file named 'node.json' with the contents:
383
-
384
- {
385
- "Data": "another",
386
- "Links": [ {
387
- "Name": "some link",
388
- "Hash": "QmXg9Pp2ytZ14xgmQjYEiHjVjMFXzCVVEcRTWJBmLgR39V",
389
- "Size": 8
390
- } ]
391
- }
392
-
393
-And then run:
394
-
395
- $ ipfs object put node.json
380
+DEPRECATED and provided for legacy reasons. Use 'ipfs dag put' instead.
381
`,
382
},
383
@@ -466,9 +451,10 @@ And then run:
451
// ObjectNewCmd object new command
452
var ObjectNewCmd = &cmds.Command{
453
Helptext: cmds.HelpText{
469
- Tagline: "Create a new dag-pb object from a template.",
454
+ Tagline: "Deprecated way to create a new dag-pb object from a template.",
455
ShortDescription: `
456
'ipfs object new' is a plumbing command for creating new dag-pb nodes.
457
+DEPRECATED and provided for legacy reasons. Use 'dag put' and 'files' instead.
458
`,
459
LongDescription: `
460
'ipfs object new' is a plumbing command for creating new dag-pb nodes.
@@ -478,6 +464,8 @@ node.
464
465
Available templates:
466
* unixfs-dir
467
+
468
+DEPRECATED and provided for legacy reasons. Use 'dag put' and 'files' instead.
469
`,
470
},
471
Arguments: []cmds.Argument{
core/commands/object/patch.go
+39
-13
@@ -13,11 +13,25 @@ import (
13
14
var ObjectPatchCmd = &cmds.Command{
15
Helptext: cmds.HelpText{
16
- Tagline: "Create a new merkledag object based on an existing one.",
16
+ Tagline: "Deprecated way to create a new merkledag object based on an existing one. Use MFS with 'files cp|rm' instead.",
17
ShortDescription: `
18
'ipfs object patch <root> <cmd> <args>' is a plumbing command used to
19
-build custom DAG objects. It mutates objects, creating new objects as a
19
+build custom dag-pb objects. It mutates objects, creating new objects as a
20
result. This is the Merkle-DAG version of modifying an object.
21
+
22
+DEPRECATED and provided for legacy reasons.
23
+For modern use cases, use MFS with 'files' commands: 'ipfs files --help'.
24
+
25
+ $ ipfs files cp /ipfs/QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn /some-dir
26
+ $ ipfs files cp /ipfs/Qmayz4F4UzqcAMitTzU4zCSckDofvxstDuj3y7ajsLLEVs /some-dir/added-file.jpg
27
+ $ ipfs files stat --hash /some-dir
28
+
29
+ The above will add 'added-file.jpg' to the directory placed under /some-dir
30
+ and the CID of updated directory is returned by 'files stat'
31
+
32
+ 'files cp' does not download the data, only the root block, which makes it
33
+ possible to build arbitrary directory trees without fetching them in full to
34
+ the local node.
35
`,
36
},
37
Arguments: []cmds.Argument{},
@@ -31,7 +45,7 @@ result. This is the Merkle-DAG version of modifying an object.
45
46
var patchAppendDataCmd = &cmds.Command{
47
Helptext: cmds.HelpText{
34
- Tagline: "Append data to the data segment of a DAG node.",
48
+ Tagline: "Deprecated way to append data to the data segment of a DAG node.",
49
ShortDescription: `
50
Append data to what already exists in the data segment in the given object.
51
@@ -40,8 +54,10 @@ Example:
54
$ echo "hello" | ipfs object patch $HASH append-data
55
56
NOTE: This does not append data to a file - it modifies the actual raw
43
-data within an object. Objects have a max size of 1MB and objects larger than
57
+data within a dag-pb object. Blocks have a max size of 1MB and objects larger than
58
the limit will not be respected by the network.
59
+
60
+DEPRECATED and provided for legacy reasons. Use 'ipfs add' or 'ipfs files' instead.
61
`,
62
},
63
Arguments: []cmds.Argument{
@@ -79,13 +95,15 @@ the limit will not be respected by the network.
95
96
var patchSetDataCmd = &cmds.Command{
97
Helptext: cmds.HelpText{
82
- Tagline: "Set the data field of an IPFS object.",
98
+ Tagline: "Deprecated way to set the data field of dag-pb object.",
99
ShortDescription: `
100
Set the data of an IPFS object from stdin or with the contents of a file.
101
102
Example:
103
104
$ echo "my data" | ipfs object patch $MYHASH set-data
105
+
106
+DEPRECATED and provided for legacy reasons. Use 'files cp' and 'dag put' instead.
107
`,
108
},
109
Arguments: []cmds.Argument{
@@ -123,9 +141,11 @@ Example:
141
142
var patchRmLinkCmd = &cmds.Command{
143
Helptext: cmds.HelpText{
126
- Tagline: "Remove a link from a given object.",
144
+ Tagline: "Deprecated way to remove a link from dag-pb object.",
145
ShortDescription: `
146
Remove a Merkle-link from the given object and return the hash of the result.
147
+
148
+DEPRECATED and provided for legacy reasons. Use 'files rm' instead.
149
`,
150
},
151
Arguments: []cmds.Argument{
@@ -163,18 +183,24 @@ const (
183
184
var patchAddLinkCmd = &cmds.Command{
185
Helptext: cmds.HelpText{
166
- Tagline: "Add a link to a given object.",
186
+ Tagline: "Deprecated way to add a link to a given dag-pb.",
187
ShortDescription: `
188
Add a Merkle-link to the given object and return the hash of the result.
189
170
-Example:
190
+DEPRECATED and provided for legacy reasons.
191
+
192
+Use MFS and 'files' commands instead:
193
+
194
+ $ ipfs files cp /ipfs/QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn /some-dir
195
+ $ ipfs files cp /ipfs/Qmayz4F4UzqcAMitTzU4zCSckDofvxstDuj3y7ajsLLEVs /some-dir/added-file.jpg
196
+ $ ipfs files stat --hash /some-dir
197
172
- $ EMPTY_DIR=$(ipfs object new unixfs-dir)
173
- $ BAR=$(echo "bar" | ipfs add -q)
174
- $ ipfs object patch $EMPTY_DIR add-link foo $BAR
198
+ The above will add 'added-file.jpg' to the directory placed under /some-dir
199
+ and the CID of updated directory is returned by 'files stat'
200
176
-This takes an empty directory, and adds a link named 'foo' under it, pointing
177
-to a file containing 'bar', and returns the hash of the new object.
201
+ 'files cp' does not download the data, only the root block, which makes it
202
+ possible to build arbitrary directory trees without fetching them in full to
203
+ the local node.
204
`,
205
},
206
Arguments: []cmds.Argument{
core/commands/root.go
-1
@@ -42,7 +42,6 @@ BASIC COMMANDS
42
DATA STRUCTURE COMMANDS
43
dag Interact with IPLD DAG nodes
44
files Interact with files as if they were a unix filesystem
45
- object Interact with dag-pb objects (deprecated, use 'dag' or 'files')
45
block Interact with raw blocks in the datastore
46
cid Convert and discover properties of CIDs
47