chef 11.6.2 → 11.8.0.rc.1

data/distro/common/man/man1/knife-cookbook.1

@@ -1,332 +1,642 @@
-.\" generated with Ronn/v0.7.3
-.\" http://github.com/rtomayko/ronn/tree/0.7.3
-.
-.TH "KNIFE\-COOKBOOK" "1" "October 2013" "Chef 11.6.2" "Chef Manual"
-.
-.SH "NAME"
-\fBknife\-cookbook\fR \- upload and manage chef cookbooks
-.
-.SH "SYNOPSIS"
-\fBknife\fR \fBcookbook\fR \fIsub\-command\fR \fI(options)\fR
-.
-.SH "SUB\-COMMANDS"
-\fBknife cookbook\fR supports the following sub commands:
-.
-.SH "LIST"
-\fBknife cookbook list\fR \fI(options)\fR
-.
-.TP
-\fB\-a\fR, \fB\-\-all\fR
-show all versions of a cookbook instead of just the most recent
-.
-.TP
-\fB\-w\fR, \fB\-\-with\-uri\fR
-show corresponding uris
-.
-.P
-Lists the cookbooks available on the Chef server\.
-.
-.SH "SHOW"
-\fBknife cookbook show cookbook [version] [part] [filename]\fR \fI(options)\fR
-.
-.TP
-\fB\-f\fR, \fB\-\-fqdn fqdn\fR
-the fqdn of the host to see the file for
-.
-.TP
-\fB\-p\fR, \fB\-\-platform platform\fR
-the platform to see the file for
-.
-.TP
-\fB\-v\fR, \fB\-\-platform\-version version\fR
-the platform version to see the file for
-.
+.TH "KNIFE-COOKBOOK" "1" "Chef 11.8.0" "" "knife cookbook"
+.SH NAME
+knife-cookbook \- The man page for the knife cookbook subcommand.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.\" Man page generated from reStructuredText.
+.
+.sp
+A cookbook is the fundamental unit of configuration and policy distribution. Each cookbook defines a scenario, such as everything needed to install and configure MySQL, and then it contains all of the components that are required to support that scenario, including:
+.INDENT 0.0
+.IP \(bu 2
+Attribute values that are set on nodes
+.IP \(bu 2
+Definitions that allow the creation of reusable collections of resources
+.IP \(bu 2
+File distributions
+.IP \(bu 2
+Libraries that extend the chef\-client and/or provide helpers to Ruby code
+.IP \(bu 2
+Recipes that specify which resources to manage and the order in which those resources will be applied
+.IP \(bu 2
+Custom resources and providers
+.IP \(bu 2
+Templates
+.IP \(bu 2
+Versions
+.IP \(bu 2
+Metadata about recipes (including dependencies), version constraints, supported platforms, and so on
+.UNINDENT
+.sp
+The \fBknife cookbook\fP subcommand is used to interact with cookbooks that are located on the server or the local chef\-repo.
+.sp
+This subcommand has the following syntax:
+.sp
+.nf
+.ft C
+$ knife cookbook [ARGUMENT] (options)
+.ft P
+.fi
+.SH COMMON OPTIONS
+.sp
+The following options can be run with all Knife sub\-commands and plug\-ins:
+.INDENT 0.0
 .TP
-\fB\-w\fR, \fB\-\-with\-uri\fR
-Show corresponding URIs
-.
-.P
-show a particular part of a \fIcookbook\fR for the specified \fIversion\fR\. \fIpart\fR can be one of:
-.
-.IP "\(bu" 4
-\fIattributes\fR
-.
-.IP "\(bu" 4
-\fIdefinitions\fR
-.
-.IP "\(bu" 4
-\fIfiles\fR
-.
-.IP "\(bu" 4
-\fIlibraries\fR
-.
-.IP "\(bu" 4
-\fIproviders\fR
-.
-.IP "\(bu" 4
-\fIrecipes\fR
-.
-.IP "\(bu" 4
-\fIresources\fR
-.
-.IP "\(bu" 4
-\fItemplates\fR
-.
-.IP "" 0
-.
-.SH "UPLOAD"
-\fBknife cookbook upload [cookbooks\.\.\.]\fR \fI(options)\fR
-.
+.B \fB\-c CONFIG\fP, \fB\-\-config CONFIG\fP
+The configuration file to use.
 .TP
-\fB\-a\fR, \fB\-\-all\fR
-upload all cookbooks, rather than just a single cookbook
-.
+.B \fB\-\-color\fP
+Indicates that colored output will be used.
 .TP
-\fB\-o\fR, \fB\-\-cookbook\-path path:path\fR
-a colon\-separated path to look for cookbooks in
-.
+.B \fB\-d\fP, \fB\-\-disable\-editing\fP
+Indicates that $EDITOR will not be opened; data will be accepted as\-is.
 .TP
-\fB\-d\fR, \fB\-\-upload\-dependencies\fR
-Uploads additional cookbooks that this cookbook lists in as dependencies in its metadata\.
-.
+.B \fB\-\-defaults\fP
+Indicates that Knife will use the default value, instead of asking a user to provide one.
 .TP
-\fB\-E\fR, \fB\-\-environment ENVIRONMENT\fR
-An \fIENVIRONMENT\fR to apply the uploaded cookbooks to\. Specifying this option will cause knife to edit the \fIENVIRONMENT\fR to place a strict version constraint on the cookbook version(s) uploaded\.
-.
+.B \fB\-e EDITOR\fP, \fB\-\-editor EDITOR\fP
+The $EDITOR that is used for all interactive commands.
 .TP
-\fB\-\-freeze\fR
-Sets the frozen flag on the uploaded cookbook(s) Any future attempt to modify the cookbook without changing the version number will return an error unless \-\-force is specified\.
-.
+.B \fB\-E ENVIRONMENT\fP, \fB\-\-environment ENVIRONMENT\fP
+The name of the environment. When this option is added to a command, the command will run only against the named environment.
 .TP
-\fB\-\-force\fR
-Overrides the frozen flag on a cookbook, allowing you to overwrite a cookbook version that has previously been uploaded with the \-\-freeze option\.
-.
-.P
-Uploads one or more cookbooks from your local cookbook repository(ies) to the Chef Server\. Only files that don\'t yet exist on the server will be uploaded\.
-.
-.P
-As the command parses the name args as 1\.\.n cookbook names: \fBknife cookbook upload COOKBOOK COOKBOOK \.\.\.\fR works for one to many cookbooks\.
-.
-.SH "DOWNLOAD"
-\fBknife cookbook download cookbook [version]\fR \fI(options)\fR
-.
+.B \fB\-f FILE_NAME\fP, \fB\-\-file FILE_NAME\fP
+Indicates that the private key will be saved to a specified file name.
 .TP
-\fB\-d\fR, \fB\-\-dir download_directory\fR
-the directory to download the cookbook into
-.
+.B \fB\-F FORMAT\fP, \fB\-\-format FORMAT\fP
+The output format: \fBsummary\fP (default), \fBtext\fP, \fBjson\fP, \fByaml\fP, and \fBpp\fP.
 .TP
-\fB\-f\fR, \fB\-\-force\fR
-overwrite an existing directory with the download
-.
+.B \fB\-h\fP, \fB\-\-help\fP
+Shows help for the command.
 .TP
-\fB\-n\fR, \fB\-\-latest\fR
-download the latest version of the cookbook
-.
-.P
-download a cookbook from the chef server\. if no version is specified and only one version exists on the server, that version will be downloaded\. if no version is specified and multiple versions are available on the server, you will be prompted for a version to download\.
-.
-.SH "DELETE"
-\fBknife cookbook delete cookbook [version]\fR \fI(options)\fR
-.
+.B \fB\-k KEY\fP, \fB\-\-key KEY\fP
+The private key that Knife will use to sign requests made by the API client to the server.
 .TP
-\fB\-a\fR, \fB\-\-all\fR
-delete all versions
-.
+.B \fB\-\-no\-color\fP
+Indicates that color will not be used in the output.
 .TP
-\fB\-p\fR, \fB\-\-purge\fR
-purge files from backing store\. this will disable any cookbook that contains any of the same files as the cookbook being purged\.
-.
-.P
-delete the specified \fIversion\fR of the named \fIcookbook\fR\. if no version is specified, and only one version exists on the server, that version will be deleted\. if multiple versions are available on the server, you will be prompted for a version to delete\.
-.
-.SH "BULK DELETE"
-\fBknife cookbook bulk delete regex\fR \fI(options)\fR
-.
+.B \fB\-p PASSWORD\fP, \fB\-\-password PASSWORD\fP
+The user password.
 .TP
-\fB\-p\fR, \fB\-\-purge\fR
-purge files from backing store\. this will disable any cookbook that contains any of the same files as the cookbook being purged\.
-.
-.P
-delete cookbooks on the chef server based on a regular expression\. the regular expression (\fIregex\fR) should be in quotes, not in //\'s\.
-.
-.SH "COOKBOOK CREATE"
-\fBknife cookbook create cookbook\fR \fI(options)\fR
-.
+.B \fB\-\-print\-after\fP
+Indicates that data will be shown after a destructive operation.
 .TP
-\fB\-o\fR, \fB\-\-cookbook\-path path\fR
-the directory where the cookbook will be created
-.
+.B \fB\-s URL\fP, \fB\-\-server\-url URL\fP
+The URL for the server.
 .TP
-\fB\-r\fR, \fB\-\-readme\-format format\fR
-format of the readme file md, mkd, txt, rdoc
-.
+.B \fB\-u USER\fP, \fB\-\-user USER\fP
+The user name used by Knife to sign requests made by the API client to the server. Authentication will fail if the user name does not match the private key.
 .TP
-\fB\-c\fR, \fB\-\-copyright copyright\fR
-name of copyright holder
-.
+.B \fB\-v\fP, \fB\-\-version\fP
+The version of the chef\-client.
 .TP
-\fB\-i\fR, \fB\-\-license license\fR
-license for cookbook, apachev2 or none
-.
+.B \fB\-V\fP, \fB\-\-verbose\fP
+Set for more verbose outputs. Use \fB\-VV\fP for maximum verbosity.
 .TP
-\fB\-e\fR, \fB\-\-email email\fR
-email address of cookbook maintainer
-.
-.P
-this is a helper command that creates a new cookbook directory in the \fBcookbook_path\fR\. the following directories and files are created for the named cookbook\.
-.
-.IP "\(bu" 4
+.B \fB\-y\fP, \fB\-\-yes\fP
+Indicates that the response to all confirmation prompts will be "Yes" (and that Knife will not ask for confirmation).
+.UNINDENT
+.SH BULK DELETE
+.sp
+The \fBbulk delete\fP argument is used to delete cookbook files that match a pattern defined by a regular expression. The regular expression must be within quotes and not be surrounded by forward slashes (/).
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.sp
+.nf
+.ft C
+$ knife cookbook bulk delete REGEX (options)
+.ft P
+.fi
+.sp
+\fBOptions\fP
+.sp
+This argument has the following options:
+.INDENT 0.0
+.TP
+.B \fB\-p\fP, \fB\-\-purge\fP
+Indicates that a cookbook (or cookbook version) will be removed entirely from the server. This action should be used carefully because only one copy of any single file is stored on the server. Consequently, purging a cookbook will disable any other cookbook that references one or more files from a cookbook that has been purged.
+.UNINDENT
+.sp
+\fBExamples\fP
+.sp
+To bulk delete many cookbooks, use a regular expression to define the pattern:
+.sp
+.nf
+.ft C
+$ knife cookbook bulk delete "^[0\-9]{3}$" \-p
+.ft P
+.fi
+.SH CREATE
+.sp
+The \fBcreate\fP argument is used to create a new cookbook directory on the local machine, including the following directories and files:
+.INDENT 0.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
 cookbook/attributes
-.
-.IP "\(bu" 4
+.IP \(bu 2
+cookbook/CHANGELOG.md
+.IP \(bu 2
 cookbook/definitions
-.
-.IP "\(bu" 4
+.IP \(bu 2
 cookbook/files/default
-.
-.IP "\(bu" 4
+.IP \(bu 2
 cookbook/libraries
-.
-.IP "\(bu" 4
-cookbook/metadata\.rb
-.
-.IP "\(bu" 4
+.IP \(bu 2
+cookbook/metadata.rb
+.IP \(bu 2
 cookbook/providers
-.
-.IP "\(bu" 4
-cookbook/readme\.md
-.
-.IP "\(bu" 4
-cookbook/recipes/default\.rb
-.
-.IP "\(bu" 4
+.IP \(bu 2
+cookbook/README.md (or .rdoc)
+.IP \(bu 2
+cookbook/recipes/default.rb
+.IP \(bu 2
 cookbook/resources
-.
-.IP "\(bu" 4
+.IP \(bu 2
 cookbook/templates/default
-.
-.IP "" 0
-.
-.P
-supported readme formats are \'md\' (default), \'mkd\', \'txt\', \'rdoc\'\. the readme file will be written with the specified extension and a set of helpful starting headers\.
-.
-.P
-specify \fB\-c\fR or \fB\-\-copyright\fR with the name of the copyright holder as your name or your company/organization name in a quoted string\. if this value is not specified an all\-caps string \fByour_company_name\fR is used which can be easily changed with find/replace\.
-.
-.P
-specify \fB\-i\fR or \fB\-\-license\fR with the license that the cookbook is distributed under for sharing with other people or posting to the opscode cookbooks site\. be aware of the licenses of files you put inside the cookbook and follow any restrictions they describe\. when using \fBnone\fR (default) or \fBapachev2\fR, comment header text and metadata file are pre\-filled\. the \fBnone\fR license will be treated as non\-redistributable\.
-.
-.P
-specify \fB\-e\fR or \fB\-\-email\fR with the email address of the cookbook\'s maintainer\. if this value is not specified, an all\-caps string \fByour_email\fR is used which can easily be changed with find/replace\.
-.
-.P
-the cookbook copyright, license, email and readme_format settings can be filled in the \fBknife\.rb\fR, for example with default values:
-.
-.IP "" 4
-.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.sp
+After the cookbook is created, it can be uploaded to the server using the \fBknife upload\fP argument.
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.sp
 .nf
-
-cookbook_copyright "your_company_name"
-cookbook_license "none"
-cookbook_email "your_email"
-readme_format "md"
-.
+.ft C
+$ knife cookbook create COOKBOOK_NAME (options)
+.ft P
 .fi
+.sp
+\fBOptions\fP
+.sp
+This argument has the following options:
+.INDENT 0.0
+.TP
+.B \fB\-C COPYRIGHT_HOLDER\fP, \fB\-\-copyright COPYRIGHT_HOLDER\fP
+The name of the copyright holder. This option will place a copyright notice that contains the name of the copyright holder in each of the pre\-created files. If this option is not specified, a copyright name of "your_company_name" will be used instead; it can be easily modified later.
+.TP
+.B \fB\-I LICENSE\fP, \fB\-\-license LICENSE\fP
+The type of license under which a cookbook is distributed: \fBapachev2\fP, \fBgplv2\fP, \fBgplv3\fP, \fBmit\fP, or \fBnone\fP (default). This option will place the appropriate license notice in the pre\-created files. Be aware of the licenses for files inside of a cookbook and be sure to follow any restrictions they describe.
+.TP
+.B \fB\-m EMAIL\fP, \fB\-\-email EMAIL\fP
+The email address for the individual who maintains the cookbook. This option will place an email address in each of the pre\-created files. If this option is not specified, an email name of "your_email" will be used instead; it can be easily modified later.
+.TP
+.B \fB\-o PATH\fP, \fB\-\-cookbook\-path PATH\fP
+The directory in which cookbook are created. This can be a colon\-separated path.
+.TP
+.B \fB\-r FORMAT\fP, \fB\-\-readme\-format FORMAT\fP
+The document format of the readme file: \fBmd\fP (markdown) and \fBrdoc\fP (Ruby docs).
+.UNINDENT
+.sp
+\fBExamples\fP
+.sp
+To create a cookbook named "my_cookbook" with copyright, email, license, and readme format options specified, enter:
+.sp
+.nf
+.ft C
+$ knife cookbook create my_cookbook \-C "My Name" \-m "my@email.com" \-I apachev2 \-r md
+.ft P
+.fi
+.sp
+to return something like:
+.sp
+.nf
+.ft C
+** Creating cookbook my_cookbook
+** Creating README for cookbook: my_cookbook
+** Creating metadata for cookbook: my_cookbook
+.ft P
+.fi
+.SH DELETE
+.sp
+The \fBdelete\fP argument is used to delete a specified cookbook or cookbook version on the server (and not locally).
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.sp
+.nf
+.ft C
+$ knife cookbook delete COOKBOOK_NAME [COOKBOOK_VERSION] (options)
+.ft P
+.fi
+.sp
+\fBOptions\fP
+.sp
+This argument has the following options:
+.INDENT 0.0
+.TP
+.B \fB\-a\fP, \fB\-\-all\fP
+Indicates that a cookbook and every version of that cookbook will be deleted.
+.TP
+.B \fBCOOKBOOK_VERSION\fP
+The version of a cookbook to be deleted. If a cookbook has only one version, this option does not need to be specified. If a cookbook has more than one version and this option is not specified, Knife will prompt for a version.
+.TP
+.B \fB\-p\fP, \fB\-\-purge\fP
+Indicates that a cookbook (or cookbook version) will be removed entirely from the server. This action should be used carefully because only one copy of any single file is stored on the server. Consequently, purging a cookbook will disable any other cookbook that references one or more files from a cookbook that has been purged.
+.UNINDENT
+.sp
+\fBExamples\fP
+.sp
+To delete version "0.8" from a cookbook named "smartmon", enter:
+.sp
+.nf
+.ft C
+$ knife cookbook delete smartmon 0.8
+.ft P
+.fi
+.sp
+Type \fBY\fP to confirm a deletion.
+.SH DOWNLOAD
+.sp
+The \fBdownload\fP argument is used to download a cookbook from the server to the current working directory.
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.sp
+.nf
+.ft C
+$ knife cookbook download COOKBOOK_NAME [COOKBOOK_VERSION] (options)
+.ft P
+.fi
+.sp
+\fBOptions\fP
+.sp
+This argument has the following options:
+.INDENT 0.0
+.TP
+.B \fB\-d DOWNLOAD_DIRECTORY\fP, \fB\-\-dir DOWNLOAD_DIRECTORY\fP
+The directory into which a cookbook will be downloaded.
+.TP
+.B \fB\-f\fP, \fB\-\-force\fP
+Indicates that an existing directory will be overwritten.
+.TP
+.B \fB\-N\fP, \fB\-\-latest\fP
+Indicates that the most recent version of a cookbook will be downloaded.
+.UNINDENT
+.sp
+\fBExamples\fP
+.sp
+To download a cookbook named "smartmon", enter:
+.sp
+.nf
+.ft C
+$ knife cookbook download smartmon
+.ft P
+.fi
+.SH LIST
+.sp
+The \fBlist\fP argument is used to view a list of cookbooks that are currently available on the server. The list will contain only the most recent version for each cookbook by default.
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.sp
+.nf
+.ft C
+$ knife cookbook list (options)
+.ft P
+.fi
+.sp
+\fBOptions\fP
+.sp
+This argument has the following options:
+.INDENT 0.0
+.TP
+.B \fB\-a\fP, \fB\-\-all\fP
+Indicates that all available versions of each cookbook will be returned.
+.TP
+.B \fB\-w\fP, \fB\-\-with\-uri\fP
+Indicates that the corresponding URIs will be shown.
+.UNINDENT
+.sp
+\fBExamples\fP
+.sp
+To view a list of cookbooks:
+.sp
+.nf
+.ft C
+$ knife cookbook list
+.ft P
+.fi
+.SH METADATA
+.sp
+The \fBmetadata\fP argument is used to generate the metadata for one or more cookbooks.
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.sp
+.nf
+.ft C
+$ knife cookbook metadata (options)
+.ft P
+.fi
+.sp
+\fBOptions\fP
+.sp
+This argument has the following options:
+.INDENT 0.0
+.TP
+.B \fB\-a\fP, \fB\-\-all\fP
+Indicates that metadata should be generated for all cookbooks, and not just for a specified cookbook.
+.TP
+.B \fB\-o PATH:PATH\fP, \fB\-\-cookbook\-path PATH:PATH\fP
+The directory in which cookbook are created. This can be a colon\-separated path.
+.UNINDENT
+.sp
+\fBExamples\fP
+.sp
+To generate metadata for all cookbooks:
+.sp
+.nf
+.ft C
+$ knife cookbook metadata \-a
+.ft P
+.fi
+.SH METADATA FROM FILE
+.sp
+The \fBmetadata from file\fP argument is used to load the metadata for a cookbook from a file.
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.sp
+.nf
+.ft C
+$ knife cookbook metadata from file FILE
+.ft P
+.fi
+.sp
+\fBOptions\fP
+.sp
+This command does not have any specific options.
+.sp
+\fBExamples\fP
+.sp
+To view cookbook metadata from a JSON file:
+.sp
+.nf
+.ft C
+$ knife cookbook metadta from file /path/to/file
+.ft P
+.fi
+.SH SHOW
+.sp
+The \fBshow\fP argument is used to view information about a cookbook, parts of a cookbook (attributes, definitions, files, libraries, providers, recipes, resources, and templates), or a file that is associated with a cookbook (including attributes such as checksum or specificity).
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.sp
+.nf
+.ft C
+$ knife cookbook show COOKBOOK_NAME [COOKBOOK_VERSION] [PART...] [FILE_NAME] (options)
+.ft P
+.fi
+.sp
+\fBOptions\fP
+.sp
+This argument has the following options:
+.INDENT 0.0
+.TP
+.B \fBCOOKBOOK_VERSION\fP
+The version of a cookbook to be shown. If a cookbook has only one version, this option does not need to be specified. If a cookbook has more than one version and this option is not specified, a list of cookbook versions will be returned.
+.TP
+.B \fB\-f FQDN\fP, \fB\-\-fqdn FQDN\fP
+The FQDN of the host.
+.TP
+.B \fBFILE_NAME\fP
+The name of a file that is associated with a cookbook.
+.TP
+.B \fB\-p PLATFORM\fP, \fB\-\-platform PLATFORM\fP
+The platform for which a cookbook is designed.
+.TP
+.B \fBPART\fP
+The part of the cookbook to show: \fBattributes\fP, \fBdefinitions\fP, \fBfiles\fP, \fBlibraries\fP, \fBproviders\fP, \fBrecipes\fP, \fBresources\fP, or \fBtemplates\fP. More than one part can be specified.
+.TP
+.B \fB\-V PLATFORM_VERSION\fP, \fB\-\-platform\-version PLATFORM_VERSION\fP
+The version of the platform.
+.TP
+.B \fB\-w\fP, \fB\-\-with\-uri\fP
+Indicates that the corresponding URIs will be shown.
+.UNINDENT
+.sp
+\fBExamples\fP
+.sp
+To get the list of available versions of a cookbook named "getting\-started", enter:
+.sp
+.nf
+.ft C
+$ knife cookbook show getting\-started
+.ft P
+.fi
+.sp
+to return something like:
+.sp
+.nf
+.ft C
+getting\-started   0.3.0  0.2.0
+.ft P
+.fi
+.sp
+To show a list of data about a cookbook using the name of the cookbook and the version, enter:
+.sp
+.nf
+.ft C
+$ knife cookbook show getting\-started 0.3.0
+.ft P
+.fi
+.sp
+to return something like:
+.sp
+.nf
+.ft C
+attributes:
+  checksum:     fa0fc4abf3f6787aeb5c3c5c35de667c
+  name:         default.rb
+  path:         attributes/default.rb
+  specificity:  default
+  url:          https://somelongurlhere.com
+chef_type:      cookbook_version
+cookbook_name:  getting\-started
+definitions:    []
+files:          []
+frozen?:        false
+json_class:     Chef::CookbookVersion
+libraries:      []
+.ft P
+.fi
+.sp
+To only view data about "templates", enter:
+.sp
+.nf
+.ft C
+$ knife cookbook show getting\-started 0.3.0 templates
+.ft P
+.fi
+.sp
+to return something like:
+.sp
+.nf
+.ft C
+checksum:     a29d6f254577b830091f140c3a78b1fe
+name:         chef\-getting\-started.txt.erb
+path:         templates/default/chef\-getting\-started.txt.erb
+specificity:  default
+url:          https://someurlhere.com
+.ft P
+.fi
+.sp
+To view information in JSON format, use the \fB\-F\fP common option as part of the command like this:
+.sp
+.nf
+.ft C
+$ knife role show devops \-F json
+.ft P
+.fi
+.sp
+Other formats available include \fBtext\fP, \fByaml\fP, and \fBpp\fP.
+.SH TEST
+.sp
+The \fBtest\fP argument is used to test a cookbook for syntax errors. This argument uses Ruby syntax checking to verify every file in a cookbook that ends in .rb and Embedded Ruby (ERB).
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.sp
+.nf
+.ft C
+$ knife cookbook test COOKBOOK_NAME (options)
+.ft P
+.fi
+.sp
+\fBOptions\fP
+.sp
+This argument has the following options:
+.INDENT 0.0
+.TP
+.B \fB\-a\fP, \fB\-\-all\fP
+Indicates that all cookbooks will be tested.
+.TP
+.B \fB\-o PATH:PATH\fP, \fB\-\-cookbook\-path PATH:PATH\fP
+The directory in which cookbook are created. This can be a colon\-separated path.
+.UNINDENT
+.sp
+\fBExamples\fP
+.sp
+To test a cookbook named "getting\-started", enter:
+.sp
+.nf
+.ft C
+$ knife cookbook test getting\-started
+.ft P
+.fi
+.SH UPLOAD
+.sp
+The \fBupload\fP argument is used to upload one or more cookbooks (and any files that are associated with those cookbooks) from a local repository to the server. Only files that do not already exist on the server will be uploaded.
+.IP Note
+Use a chefignore file to prevent the upload of specific files and file types, such as temporary files or files placed in folders by version control systems. The chefignore file must be located in the root of the cookbook repository and must use rules similar to filename globbing (as defined by the Ruby \fBFile.fnmatch\fP syntax).
+.RE
+.sp
+\fBSyntax\fP
+.sp
+This argument has the following syntax:
+.sp
+.nf
+.ft C
+$ knife cookbook upload [COOKBOOK_NAME...] (options)
+.ft P
+.fi
+.sp
+\fBOptions\fP
+.sp
+This argument has the following options:
+.INDENT 0.0
+.TP
+.B \fB\-a\fP, \fB\-\-all\fP
+Indicates that all cookbooks will be uploaded.
+.TP
+.B \fB\-d\fP, \fB\-\-include\-dependencies\fP
+Indicates that when a cookbook has a dependency on one (or more) cookbooks, those cookbooks will also be uploaded.
+.TP
+.B \fB\-\-force\fP
+Indicates that a cookbook should be updated even if the \fB\-\-freeze\fP flag has been set.
+.TP
+.B \fB\-\-freeze\fP
+Indicates that a cookbook cannot be modified; any changes to this cookbook must be included as a new version. Only the \fB\-\-force\fP option can override this setting.
+.TP
+.B \fB\-o PATH:PATH\fP, \fB\-\-cookbook\-path PATH:PATH\fP
+The directory in which cookbook are created. This can be a colon\-separated path.
+.UNINDENT
+.sp
+\fBExamples\fP
+.sp
+To upload a cookbook named "getting\-started":
+.sp
+.nf
+.ft C
+$ knife cookbook upload getting\-started
+.ft P
+.fi
+.sp
+To upload a cookbook, and then prevent other users from being able to make changes to it, enter:
+.sp
+.nf
+.ft C
+$ knife cookbook upload redis \-\-freeze
+.ft P
+.fi
+.sp
+to return something like:
+.sp
+.nf
+.ft C
+Uploading redis...
+Upload completed
+.ft P
+.fi
+.sp
+If a cookbook is frozen and the \fB\-\-force\fP option is not specified, Knife will return an error message similar to the following:
+.sp
+.nf
+.ft C
+Uploading redis...
+ERROR: Version 0.1.6 of cookbook redis is frozen. Use \-\-force to override.
+.ft P
+.fi
+.SH AUTHOR
+Opscode
+.\" Generated by docutils manpage writer.
 .
-.IP "" 0
-.
-.SH "METADATA"
-\fBknife cookbook metadata cookbook\fR \fI(options)\fR
-.
-.TP
-\fB\-a\fR, \fB\-\-all\fR
-generate metadata for all cookbooks, rather than just a single cookbook
-.
-.TP
-\fB\-o\fR, \fB\-\-cookbook\-path path:path\fR
-a colon\-separated path to look for cookbooks in
-.
-.P
-generate cookbook metadata for the named \fIcookbook\fR\. the \fIpath\fR used here specifies where the cookbooks directory is located and corresponds to the \fBcookbook_path\fR configuration option\.
-.
-.SH "METADATA FROM FILE"
-\fBknife cookbook metadata from file\fR \fI(options)\fR
-.
-.P
-load the cookbook metadata from a specified file\.
-.
-.SH "TEST"
-\fBknife cookbook test [cookbooks\.\.\.]\fR \fI(options)\fR
-.
-.TP
-\fB\-a\fR, \fB\-\-all\fR
-test all cookbooks, rather than just a single cookbook
-.
-.TP
-\fB\-o\fR, \fB\-\-cookbook\-path path:path\fR
-a colon\-separated path to look for cookbooks in
-.
-.P
-test the specified cookbooks for syntax errors\. this uses the built\-in ruby syntax checking option for files in the cookbook ending in \fB\.rb\fR, and the erb syntax check for files ending in \fB\.erb\fR (templates)\.
-.
-.SH "RECIPE LIST"
-\fBknife recipe list [PATTERN]\fR
-.
-.P
-List available recipes from the server\. Specify \fIPATTERN\fR as a regular expression to limit the results\.
-.
-.SH "DESCRIPTION"
-Cookbooks are the fundamental unit of distribution in Chef\. They encapsulate all recipes of resources and assets used to configure a particular aspect of the infrastructure\. The following sub\-commands can be used to manipulate the cookbooks stored on the Chef Server\.
-.
-.P
-On disk, cookbooks are directories with a defined structure\. The following directories may appear within a cookbook:
-.
-.TP
-COOKBOOK/attributes/
-Ruby files that define default parameters to be used in recipes
-.
-.TP
-COOKBOOK/definitions/
-Ruby files that contain \fIresource definitions\fR
-.
-.TP
-COOKBOOK/files/SPECIFICITY
-Files of arbitrary type\. These files may be downloaded by chef\-client(8) when configuring a host\.
-.
-.TP
-COOKBOOK/libraries/
-Ruby files that contain library code needed for recipes
-.
-.TP
-COOKBOOK/providers/
-Ruby files that contain Lightweight Provider definitions
-.
-.TP
-COOKBOOK/recipes/
-Ruby files that use Chef\'s recipe DSL to describe the desired configuration of a system
-.
-.TP
-COOKBOOK/resources/
-Ruby files that contain Lightweight Resource definitions
-.
-.TP
-COOKBOOK/templates/SPECIFICITY
-ERuby (ERb) template files\. These are referenced by \fIrecipes\fR and evaluated to dynamically generate configuration files\.
-.
-.P
-\fBSPECIFICITY\fR is a feature of \fIfiles\fR and \fItemplates\fR that allow you to specify alternate files to be used on a specific OS platform or host\. The default specificity setting is \fIdefault\fR, that is files in \fBCOOKBOOK/files/default\fR will be used when a more specific copy is not available\. Further documentation for this feature is available on the Chef wiki: \fIhttp://wiki\.opscode\.com/display/chef/File+Distribution#FileDistribution\-FileSpecificity\fR
-.
-.P
-Cookbooks also contain a metadata file that defines various properties of the cookbook\. The most important of these are the \fIversion\fR and the \fIdependencies\fR\. The \fIversion\fR is used in combination with environments to select which copy of a given cookbook is distributed to a node\. The \fIdependencies\fR are used by the server to determine which additional cookbooks must be distributed to a given host when it requires a cookbook\.
-.
-.SH "SEE ALSO"
-\fBknife\-environment(1)\fR \fBknife\-cookbook\-site(1)\fR \fIhttp://wiki\.opscode\.com/display/chef/Cookbooks\fR \fIhttp://wiki\.opscode\.com/display/chef/Metadata\fR
-.
-.SH "AUTHOR"
-Chef was written by Adam Jacob \fIadam@opscode\.com\fR with many contributions from the community\.
-.
-.SH "DOCUMENTATION"
-This manual page was written by Joshua Timberman \fIjoshua@opscode\.com\fR\. Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2\.0 License\.
-.
-.SH "CHEF"
-Knife is distributed with Chef\. \fIhttp://wiki\.opscode\.com/display/chef/Home\fR