Merge pull request #8098 from ipfs/docs/deprecate-object-cmds

docs: deprecate object commands

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

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 <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,16 +273,42 @@ 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
 	BlockSize       int size of the raw, encoded data
 	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{

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 <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.
+
+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{

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