mirror of
https://github.com/ipfs/kubo.git
synced 2026-02-21 10:27:46 +08:00
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/
This commit is contained in:
Marcin Rataj
parent
eea198f081
commit
8c1e4e99d1
@ -298,7 +298,6 @@ SUBCOMMANDS
|
||||
DATA STRUCTURE COMMANDS
|
||||
dag Interact with IPLD DAG nodes
|
||||
files Interact with files as if they were a unix filesystem
|
||||
object Interact with dag-pb objects (deprecated, use 'dag' or 'files')
|
||||
block Interact with raw blocks in the datastore
|
||||
|
||||
ADVANCED COMMANDS
|
||||
|
||||
@ -48,7 +48,7 @@ const (
|
||||
|
||||
var ObjectCmd = &cmds.Command{
|
||||
Helptext: cmds.HelpText{
|
||||
Tagline: "Interact with dag-pb objects (deprecated, use generic 'dag')",
|
||||
Tagline: "Deprecated commands to interact with dag-pb objects. Use 'dag' or 'files' instead.",
|
||||
ShortDescription: `
|
||||
'ipfs object' is a legacy plumbing command used to manipulate dag-pb objects
|
||||
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.`,
|
||||
// ObjectDataCmd object data command
|
||||
var ObjectDataCmd = &cmds.Command{
|
||||
Helptext: cmds.HelpText{
|
||||
Tagline: "Output the raw bytes of a dag-pb object.",
|
||||
Tagline: "Deprecated way to read the raw bytes of a dag-pb object: use 'dag get' instead.",
|
||||
ShortDescription: `
|
||||
'ipfs object data' is a plumbing command for retrieving the raw bytes stored
|
||||
in a dag-pb node. It outputs to stdout, and <key> is a base58 encoded multihash.
|
||||
'ipfs object data' is a deprecated plumbing command for retrieving the raw
|
||||
bytes stored in a dag-pb node. It outputs to stdout, and <key> is a base58
|
||||
encoded multihash. Provided for legacy reasons. Use 'ipfs dag get' instead.
|
||||
`,
|
||||
LongDescription: `
|
||||
'ipfs object data' is a plumbing command for retrieving the raw bytes stored
|
||||
in a dag-pb node. It outputs to stdout, and <key> is a base58 encoded multihash.
|
||||
'ipfs object data' is a deprecated plumbing command for retrieving the raw
|
||||
bytes stored in a dag-pb node. It outputs to stdout, and <key> is a base58
|
||||
encoded multihash. Provided for legacy reasons. Use 'ipfs dag get' instead.
|
||||
|
||||
Note that the "--encoding" option does not affect the output, since the output
|
||||
is the raw data of the object.
|
||||
@ -106,11 +108,11 @@ is the raw data of the object.
|
||||
// ObjectLinksCmd object links command
|
||||
var ObjectLinksCmd = &cmds.Command{
|
||||
Helptext: cmds.HelpText{
|
||||
Tagline: "Output the links pointed to by the specified dag-pb object.",
|
||||
Tagline: "Deprecated way to output links in the specified dag-pb object: use 'dag get' instead.",
|
||||
ShortDescription: `
|
||||
'ipfs object links' is a plumbing command for retrieving the links from
|
||||
a dag-pb node. It outputs to stdout, and <key> is a base58 encoded
|
||||
multihash.
|
||||
multihash. Provided for legacy reasons. Use 'ipfs dag get' instead.
|
||||
`,
|
||||
},
|
||||
|
||||
@ -180,29 +182,13 @@ multihash.
|
||||
// ObjectGetCmd object get command
|
||||
var ObjectGetCmd = &cmds.Command{
|
||||
Helptext: cmds.HelpText{
|
||||
Tagline: "Get and serialize the dag-pb node named by <key>.",
|
||||
Tagline: "Deprecated way to get and serialize the dag-pb node. Use 'dag get' instead",
|
||||
ShortDescription: `
|
||||
'ipfs object get' is a plumbing command for retrieving dag-pb nodes.
|
||||
It serializes the DAG node to the format specified by the "--encoding"
|
||||
flag. It outputs to stdout, and <key> is a base58 encoded multihash.
|
||||
`,
|
||||
LongDescription: `
|
||||
'ipfs object get' is a plumbing command for retrieving dag-pb nodes.
|
||||
It serializes the DAG node to the format specified by the "--encoding"
|
||||
flag. It outputs to stdout, and <key> is a base58 encoded multihash.
|
||||
|
||||
This command outputs data in the following encodings:
|
||||
* "protobuf"
|
||||
* "json"
|
||||
* "xml"
|
||||
(Specified by the "--encoding" or "--enc" flag)
|
||||
|
||||
The encoding of the object's data field can be specified by using the
|
||||
--data-encoding flag
|
||||
|
||||
Supported values are:
|
||||
* "text" (default)
|
||||
* "base64"
|
||||
DEPRECATED and provided for legacy reasons. Use 'ipfs dag get' instead.
|
||||
`,
|
||||
},
|
||||
|
||||
@ -287,9 +273,15 @@ Supported values are:
|
||||
// ObjectStatCmd object stat command
|
||||
var ObjectStatCmd = &cmds.Command{
|
||||
Helptext: cmds.HelpText{
|
||||
Tagline: "Get stats for the dag-pb node named by <key>.",
|
||||
Tagline: "Deprecated way to read stats for the dag-pb node. Use 'files stat' instead.",
|
||||
ShortDescription: `
|
||||
'ipfs object stat' is a plumbing command to print dag-pb node statistics.
|
||||
<key> is a base58 encoded multihash.
|
||||
|
||||
DEPRECATED: modern replacements are 'files stat' and 'dag stat'
|
||||
`,
|
||||
LongDescription: `
|
||||
'ipfs object stat' is a plumbing command to print dag-pb node statistics.
|
||||
<key> is a base58 encoded multihash. It outputs to stdout:
|
||||
|
||||
NumLinks int number of links in link table
|
||||
@ -297,6 +289,26 @@ var ObjectStatCmd = &cmds.Command{
|
||||
LinksSize int size of the links segment
|
||||
DataSize int size of the data segment
|
||||
CumulativeSize int cumulative size of object and its references
|
||||
|
||||
DEPRECATED: Provided for legacy reasons. Modern replacements:
|
||||
|
||||
For unixfs, 'ipfs files stat' can be used:
|
||||
|
||||
$ ipfs files stat --with-local /ipfs/QmWfVY9y3xjsixTgbd9AorQxH7VtMpzfx2HaWtsoUYecaX
|
||||
QmWfVY9y3xjsixTgbd9AorQxH7VtMpzfx2HaWtsoUYecaX
|
||||
Size: 5
|
||||
CumulativeSize: 13
|
||||
ChildBlocks: 0
|
||||
Type: file
|
||||
Local: 13 B of 13 B (100.00%)
|
||||
|
||||
Reported sizes are based on metadata present in root block, and should not be
|
||||
trusted. A slower, but more secure alternative is 'ipfs dag stat', which
|
||||
will work for every DAG type. It comes with a benefit of calculating the
|
||||
size by walking the DAG:
|
||||
|
||||
$ ipfs dag stat /ipfs/QmWfVY9y3xjsixTgbd9AorQxH7VtMpzfx2HaWtsoUYecaX
|
||||
Size: 13, NumBlocks: 1
|
||||
`,
|
||||
},
|
||||
|
||||
@ -360,39 +372,12 @@ var ObjectStatCmd = &cmds.Command{
|
||||
// ObjectPutCmd object put command
|
||||
var ObjectPutCmd = &cmds.Command{
|
||||
Helptext: cmds.HelpText{
|
||||
Tagline: "Store input as a dag-pb object, print its key.",
|
||||
Tagline: "Deprecated way to store input as a DAG object. Use 'dag put' instead.",
|
||||
ShortDescription: `
|
||||
'ipfs object put' is a plumbing command for storing dag-pb nodes.
|
||||
It reads from stdin, and the output is a base58 encoded multihash.
|
||||
`,
|
||||
LongDescription: `
|
||||
'ipfs object put' is a plumbing command for storing dag-pb nodes.
|
||||
It reads from stdin, and the output is a base58 encoded multihash.
|
||||
|
||||
Data should be in the format specified by the --inputenc flag.
|
||||
--inputenc may be one of the following:
|
||||
* "protobuf"
|
||||
* "json" (default)
|
||||
|
||||
Examples:
|
||||
|
||||
$ echo '{ "Data": "abc" }' | ipfs object put
|
||||
|
||||
This creates a node with the data 'abc' and no links. For an object with
|
||||
links, create a file named 'node.json' with the contents:
|
||||
|
||||
{
|
||||
"Data": "another",
|
||||
"Links": [ {
|
||||
"Name": "some link",
|
||||
"Hash": "QmXg9Pp2ytZ14xgmQjYEiHjVjMFXzCVVEcRTWJBmLgR39V",
|
||||
"Size": 8
|
||||
} ]
|
||||
}
|
||||
|
||||
And then run:
|
||||
|
||||
$ ipfs object put node.json
|
||||
DEPRECATED and provided for legacy reasons. Use 'ipfs dag put' instead.
|
||||
`,
|
||||
},
|
||||
|
||||
@ -466,9 +451,10 @@ And then run:
|
||||
// ObjectNewCmd object new command
|
||||
var ObjectNewCmd = &cmds.Command{
|
||||
Helptext: cmds.HelpText{
|
||||
Tagline: "Create a new dag-pb object from a template.",
|
||||
Tagline: "Deprecated way to create a new dag-pb object from a template.",
|
||||
ShortDescription: `
|
||||
'ipfs object new' is a plumbing command for creating new dag-pb nodes.
|
||||
DEPRECATED and provided for legacy reasons. Use 'dag put' and 'files' instead.
|
||||
`,
|
||||
LongDescription: `
|
||||
'ipfs object new' is a plumbing command for creating new dag-pb nodes.
|
||||
@ -478,6 +464,8 @@ node.
|
||||
|
||||
Available templates:
|
||||
* unixfs-dir
|
||||
|
||||
DEPRECATED and provided for legacy reasons. Use 'dag put' and 'files' instead.
|
||||
`,
|
||||
},
|
||||
Arguments: []cmds.Argument{
|
||||
|
||||
@ -13,11 +13,25 @@ import (
|
||||
|
||||
var ObjectPatchCmd = &cmds.Command{
|
||||
Helptext: cmds.HelpText{
|
||||
Tagline: "Create a new merkledag object based on an existing one.",
|
||||
Tagline: "Deprecated way to create a new merkledag object based on an existing one. Use MFS with 'files cp|rm' instead.",
|
||||
ShortDescription: `
|
||||
'ipfs object patch <root> <cmd> <args>' is a plumbing command used to
|
||||
build custom DAG objects. It mutates objects, creating new objects as a
|
||||
build custom dag-pb objects. It mutates objects, creating new objects as a
|
||||
result. This is the Merkle-DAG version of modifying an object.
|
||||
|
||||
DEPRECATED and provided for legacy reasons.
|
||||
For modern use cases, use MFS with 'files' commands: 'ipfs files --help'.
|
||||
|
||||
$ ipfs files cp /ipfs/QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn /some-dir
|
||||
$ ipfs files cp /ipfs/Qmayz4F4UzqcAMitTzU4zCSckDofvxstDuj3y7ajsLLEVs /some-dir/added-file.jpg
|
||||
$ ipfs files stat --hash /some-dir
|
||||
|
||||
The above will add 'added-file.jpg' to the directory placed under /some-dir
|
||||
and the CID of updated directory is returned by 'files stat'
|
||||
|
||||
'files cp' does not download the data, only the root block, which makes it
|
||||
possible to build arbitrary directory trees without fetching them in full to
|
||||
the local node.
|
||||
`,
|
||||
},
|
||||
Arguments: []cmds.Argument{},
|
||||
@ -31,7 +45,7 @@ result. This is the Merkle-DAG version of modifying an object.
|
||||
|
||||
var patchAppendDataCmd = &cmds.Command{
|
||||
Helptext: cmds.HelpText{
|
||||
Tagline: "Append data to the data segment of a DAG node.",
|
||||
Tagline: "Deprecated way to append data to the data segment of a DAG node.",
|
||||
ShortDescription: `
|
||||
Append data to what already exists in the data segment in the given object.
|
||||
|
||||
@ -40,8 +54,10 @@ Example:
|
||||
$ echo "hello" | ipfs object patch $HASH append-data
|
||||
|
||||
NOTE: This does not append data to a file - it modifies the actual raw
|
||||
data within an object. Objects have a max size of 1MB and objects larger than
|
||||
data within a dag-pb object. Blocks have a max size of 1MB and objects larger than
|
||||
the limit will not be respected by the network.
|
||||
|
||||
DEPRECATED and provided for legacy reasons. Use 'ipfs add' or 'ipfs files' instead.
|
||||
`,
|
||||
},
|
||||
Arguments: []cmds.Argument{
|
||||
@ -79,13 +95,15 @@ the limit will not be respected by the network.
|
||||
|
||||
var patchSetDataCmd = &cmds.Command{
|
||||
Helptext: cmds.HelpText{
|
||||
Tagline: "Set the data field of an IPFS object.",
|
||||
Tagline: "Deprecated way to set the data field of dag-pb object.",
|
||||
ShortDescription: `
|
||||
Set the data of an IPFS object from stdin or with the contents of a file.
|
||||
|
||||
Example:
|
||||
|
||||
$ echo "my data" | ipfs object patch $MYHASH set-data
|
||||
|
||||
DEPRECATED and provided for legacy reasons. Use 'files cp' and 'dag put' instead.
|
||||
`,
|
||||
},
|
||||
Arguments: []cmds.Argument{
|
||||
@ -123,9 +141,11 @@ Example:
|
||||
|
||||
var patchRmLinkCmd = &cmds.Command{
|
||||
Helptext: cmds.HelpText{
|
||||
Tagline: "Remove a link from a given object.",
|
||||
Tagline: "Deprecated way to remove a link from dag-pb object.",
|
||||
ShortDescription: `
|
||||
Remove a Merkle-link from the given object and return the hash of the result.
|
||||
|
||||
DEPRECATED and provided for legacy reasons. Use 'files rm' instead.
|
||||
`,
|
||||
},
|
||||
Arguments: []cmds.Argument{
|
||||
@ -163,18 +183,24 @@ const (
|
||||
|
||||
var patchAddLinkCmd = &cmds.Command{
|
||||
Helptext: cmds.HelpText{
|
||||
Tagline: "Add a link to a given object.",
|
||||
Tagline: "Deprecated way to add a link to a given dag-pb.",
|
||||
ShortDescription: `
|
||||
Add a Merkle-link to the given object and return the hash of the result.
|
||||
|
||||
Example:
|
||||
DEPRECATED and provided for legacy reasons.
|
||||
|
||||
$ EMPTY_DIR=$(ipfs object new unixfs-dir)
|
||||
$ BAR=$(echo "bar" | ipfs add -q)
|
||||
$ ipfs object patch $EMPTY_DIR add-link foo $BAR
|
||||
Use MFS and 'files' commands instead:
|
||||
|
||||
This takes an empty directory, and adds a link named 'foo' under it, pointing
|
||||
to a file containing 'bar', and returns the hash of the new object.
|
||||
$ ipfs files cp /ipfs/QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn /some-dir
|
||||
$ ipfs files cp /ipfs/Qmayz4F4UzqcAMitTzU4zCSckDofvxstDuj3y7ajsLLEVs /some-dir/added-file.jpg
|
||||
$ ipfs files stat --hash /some-dir
|
||||
|
||||
The above will add 'added-file.jpg' to the directory placed under /some-dir
|
||||
and the CID of updated directory is returned by 'files stat'
|
||||
|
||||
'files cp' does not download the data, only the root block, which makes it
|
||||
possible to build arbitrary directory trees without fetching them in full to
|
||||
the local node.
|
||||
`,
|
||||
},
|
||||
Arguments: []cmds.Argument{
|
||||
|
||||
@ -42,7 +42,6 @@ BASIC COMMANDS
|
||||
DATA STRUCTURE COMMANDS
|
||||
dag Interact with IPLD DAG nodes
|
||||
files Interact with files as if they were a unix filesystem
|
||||
object Interact with dag-pb objects (deprecated, use 'dag' or 'files')
|
||||
block Interact with raw blocks in the datastore
|
||||
cid Convert and discover properties of CIDs
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user