diff --git a/README.md b/README.md index 81b4e89fed4..2dafe8a739c 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/core/commands/object/object.go b/core/commands/object/object.go index 1e52f231566..1e145208a59 100644 --- a/core/commands/object/object.go +++ b/core/commands/object/object.go @@ -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 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 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 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 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 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 .", + 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 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 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 .", + 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. + 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. 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{ diff --git a/core/commands/object/patch.go b/core/commands/object/patch.go index 2f0239cec10..c98f125065c 100644 --- a/core/commands/object/patch.go +++ b/core/commands/object/patch.go @@ -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 ' 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. + +Use MFS and 'files' commands instead: + + $ ipfs files cp /ipfs/QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn /some-dir + $ ipfs files cp /ipfs/Qmayz4F4UzqcAMitTzU4zCSckDofvxstDuj3y7ajsLLEVs /some-dir/added-file.jpg + $ ipfs files stat --hash /some-dir - $ EMPTY_DIR=$(ipfs object new unixfs-dir) - $ BAR=$(echo "bar" | ipfs add -q) - $ ipfs object patch $EMPTY_DIR add-link foo $BAR + 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' -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. + '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{ diff --git a/core/commands/root.go b/core/commands/root.go index 8aa1d7e1e45..b6a7f639fef 100644 --- a/core/commands/root.go +++ b/core/commands/root.go @@ -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