Regenerating man pages for 1.1.0 dev release1.1.0

16 files changed, 105 insertions, 123 deletions

diff --git a/man/bst-artifact-receive.1 b/man/bst-artifact-receive.1
index 8054e68ae..475a4d6a9 100644
--- a/man/bst-artifact-receive.1
+++ b/man/bst-artifact-receive.1
@@ -1,4 +1,4 @@
-.TH "BST-ARTIFACT-RECEIVE" "1" "10-Sep-2017" "" "bst-artifact-receive Manual"
+.TH "BST-ARTIFACT-RECEIVE" "1" "19-Feb-2018" "" "bst-artifact-receive Manual"
 .SH NAME
 bst-artifact-receive \- Receive pushed artifacts over ssh
 .SH SYNOPSIS
@@ -13,4 +13,7 @@ A BuildStream sister program for receiving artifacts send to a shared artifact c
 Verbose mode
 .TP
 \fB\-d,\fP \-\-debug
-Debug mode
\ No newline at end of file
+Debug mode
+.TP
+\fB\-\-pull\-url\fP TEXT
+Clients who try to pull over SSH will be redirected here  [required]
\ No newline at end of file
diff --git a/man/bst-build.1 b/man/bst-build.1
index d22d1787d..ed03acc9d 100644
--- a/man/bst-build.1
+++ b/man/bst-build.1
@@ -1,9 +1,9 @@
-.TH "BST BUILD" "1" "10-Sep-2017" "" "bst build Manual"
+.TH "BST BUILD" "1" "19-Feb-2018" "" "bst build Manual"
 .SH NAME
 bst\-build \- Build elements in a pipeline
 .SH SYNOPSIS
 .B bst build
-[OPTIONS] TARGET
+[OPTIONS] [ELEMENTS]...
 .SH DESCRIPTION
 Build elements in a pipeline
 .SH OPTIONS
@@ -11,8 +11,14 @@ Build elements in a pipeline
 \fB\-\-all\fP
 Build elements that would not be needed for the current build plan
 .TP
-\fB\-\-track\fP
-Track new source references before building (implies --all)
+\fB\-\-track\fP PATH
+Specify elements to track during the build. Can be used repeatedly to specify multiple elements
 .TP
-\fB\-\-variant\fP TEXT
-A variant of the specified target
\ No newline at end of file
+\fB\-\-track\-all\fP
+Track all elements in the pipeline
+.TP
+\fB\-\-track\-except\fP PATH
+Except certain dependencies from tracking
+.TP
+\fB\-\-track\-save\fP
+Write out the tracked references to their element files
\ No newline at end of file
diff --git a/man/bst-checkout.1 b/man/bst-checkout.1
index 6fb64ced8..6276bd5ab 100644
--- a/man/bst-checkout.1
+++ b/man/bst-checkout.1
@@ -1,9 +1,9 @@
-.TH "BST CHECKOUT" "1" "10-Sep-2017" "" "bst checkout Manual"
+.TH "BST CHECKOUT" "1" "19-Feb-2018" "" "bst checkout Manual"
 .SH NAME
 bst\-checkout \- Checkout a built artifact
 .SH SYNOPSIS
 .B bst checkout
-[OPTIONS] TARGET DIRECTORY
+[OPTIONS] ELEMENT DIRECTORY
 .SH DESCRIPTION
 Checkout a built artifact to the specified directory
     
@@ -12,5 +12,8 @@ Checkout a built artifact to the specified directory
 \fB\-f,\fP \-\-force
 Overwrite files existing in checkout directory
 .TP
-\fB\-\-variant\fP TEXT
-A variant of the specified target
\ No newline at end of file
+\fB\-\-integrate\fP / \-\-no\-integrate
+Whether to run integration commands
+.TP
+\fB\-\-hardlinks\fP
+Checkout hardlinks instead of copies (handle with care)
\ No newline at end of file
diff --git a/man/bst-fetch.1 b/man/bst-fetch.1
index 046549bd6..c2cae276d 100644
--- a/man/bst-fetch.1
+++ b/man/bst-fetch.1
@@ -1,9 +1,9 @@
-.TH "BST FETCH" "1" "10-Sep-2017" "" "bst fetch Manual"
+.TH "BST FETCH" "1" "19-Feb-2018" "" "bst fetch Manual"
 .SH NAME
 bst\-fetch \- Fetch sources in a pipeline
 .SH SYNOPSIS
 .B bst fetch
-[OPTIONS] TARGET
+[OPTIONS] [ELEMENTS]...
 .SH DESCRIPTION
 Fetch sources required to build the pipeline
 
@@ -20,14 +20,11 @@ Specify `--deps` to control which sources to fetch:
     all:   All dependencies
 .SH OPTIONS
 .TP
-\fB\-\-except\fP TEXT
+\fB\-\-except\fP PATH
 Except certain dependencies from fetching
 .TP
 \fB\-d,\fP \-\-deps [none|plan|all]
 The dependencies to fetch (default: plan)
 .TP
 \fB\-\-track\fP
-Track new source references before fetching
-.TP
-\fB\-\-variant\fP TEXT
-A variant of the specified target
\ No newline at end of file
+Track new source references before fetching
\ No newline at end of file
diff --git a/man/bst-pull.1 b/man/bst-pull.1
index fe66a662c..5fc82f9c8 100644
--- a/man/bst-pull.1
+++ b/man/bst-pull.1
@@ -1,12 +1,16 @@
-.TH "BST PULL" "1" "10-Sep-2017" "" "bst pull Manual"
+.TH "BST PULL" "1" "19-Feb-2018" "" "bst pull Manual"
 .SH NAME
 bst\-pull \- Pull a built artifact
 .SH SYNOPSIS
 .B bst pull
-[OPTIONS] TARGET
+[OPTIONS] [ELEMENTS]...
 .SH DESCRIPTION
 Pull a built artifact from the configured remote artifact cache.
 
+By default the artifact will be pulled one of the configured caches
+if possible, following the usual priority order. If the `--remote` flag
+is given, only the specified cache will be queried.
+
 Specify `--deps` to control which artifacts to pull:
 
 
@@ -14,8 +18,8 @@ Specify `--deps` to control which artifacts to pull:
     all:   All dependencies
 .SH OPTIONS
 .TP
-\fB\-\-variant\fP TEXT
-A variant of the specified target
-.TP
 \fB\-d,\fP \-\-deps [none|all]
-The dependency artifacts to pull (default: none)
\ No newline at end of file
+The dependency artifacts to pull (default: none)
+.TP
+\fB\-r,\fP \-\-remote TEXT
+The URL of the remote cache (defaults to the first configured cache)
\ No newline at end of file
diff --git a/man/bst-push.1 b/man/bst-push.1
index a68eb5dda..0625e124f 100644
--- a/man/bst-push.1
+++ b/man/bst-push.1
@@ -1,11 +1,14 @@
-.TH "BST PUSH" "1" "10-Sep-2017" "" "bst push Manual"
+.TH "BST PUSH" "1" "19-Feb-2018" "" "bst push Manual"
 .SH NAME
 bst\-push \- Push a built artifact
 .SH SYNOPSIS
 .B bst push
-[OPTIONS] TARGET
+[OPTIONS] [ELEMENTS]...
 .SH DESCRIPTION
-Push a built artifact to the configured remote artifact cache.
+Push a built artifact to a remote artifact cache.
+
+The default destination is the highest priority configured cache. You can
+override this by passing a different cache URL with the `--remote` flag.
 
 Specify `--deps` to control which artifacts to push:
 
@@ -14,8 +17,8 @@ Specify `--deps` to control which artifacts to push:
     all:   All dependencies
 .SH OPTIONS
 .TP
-\fB\-\-variant\fP TEXT
-A variant of the specified target
-.TP
 \fB\-d,\fP \-\-deps [none|all]
-The dependencies to push (default: none)
\ No newline at end of file
+The dependencies to push (default: none)
+.TP
+\fB\-r,\fP \-\-remote TEXT
+The URL of the remote cache (defaults to the first configured cache)
\ No newline at end of file
diff --git a/man/bst-shell.1 b/man/bst-shell.1
index 7c53ff1dc..236b571ee 100644
--- a/man/bst-shell.1
+++ b/man/bst-shell.1
@@ -1,9 +1,9 @@
-.TH "BST SHELL" "1" "10-Sep-2017" "" "bst shell Manual"
+.TH "BST SHELL" "1" "19-Feb-2018" "" "bst shell Manual"
 .SH NAME
 bst\-shell \- Shell into an element's sandbox environment
 .SH SYNOPSIS
 .B bst shell
-[OPTIONS] TARGET [COMMAND]...
+[OPTIONS] ELEMENT [COMMAND]...
 .SH DESCRIPTION
 Run a command in the target element's sandbox environment
 
@@ -26,7 +26,4 @@ to run an interactive shell with `sh -i`.
 Create a build sandbox
 .TP
 \fB\-s,\fP \-\-sysroot DIRECTORY
-An existing sysroot
-.TP
-\fB\-\-variant\fP TEXT
-A variant of the specified target
\ No newline at end of file
+An existing sysroot
\ No newline at end of file
diff --git a/man/bst-show.1 b/man/bst-show.1
index 8d1e5ab15..35f6b8e73 100644
--- a/man/bst-show.1
+++ b/man/bst-show.1
@@ -1,9 +1,9 @@
-.TH "BST SHOW" "1" "10-Sep-2017" "" "bst show Manual"
+.TH "BST SHOW" "1" "19-Feb-2018" "" "bst show Manual"
 .SH NAME
 bst\-show \- Show elements in the pipeline
 .SH SYNOPSIS
 .B bst show
-[OPTIONS] TARGET
+[OPTIONS] [ELEMENTS]...
 .SH DESCRIPTION
 Show elements in the pipeline
 
@@ -27,7 +27,6 @@ the following symbols can be used in the format string:
 
 
     %{name}           The element name
-    %{variant}        The selected element variant
     %{key}            The abbreviated cache key (if all sources are consistent)
     %{full-key}       The full cache key (if all sources are consistent)
     %{state}          cached, buildable, waiting or inconsistent
@@ -53,7 +52,7 @@ If you want to use a newline in a format string in bash, use the '$' modifier:
         $'---------- %{name} ----------\n%{vars}'
 .SH OPTIONS
 .TP
-\fB\-\-except\fP TEXT
+\fB\-\-except\fP PATH
 Except certain dependencies
 .TP
 \fB\-d,\fP \-\-deps [none|plan|run|build|all]
@@ -65,5 +64,5 @@ Staging or alphabetic ordering of dependencies
 \fB\-f,\fP \-\-format FORMAT
 Format string for each element
 .TP
-\fB\-\-variant\fP TEXT
-A variant of the specified target
\ No newline at end of file
+\fB\-\-downloadable\fP
+Refresh downloadable state
\ No newline at end of file
diff --git a/man/bst-source-bundle.1 b/man/bst-source-bundle.1
index 28a61c825..34063c045 100644
--- a/man/bst-source-bundle.1
+++ b/man/bst-source-bundle.1
@@ -1,4 +1,4 @@
-.TH "BST SOURCE-BUNDLE" "1" "10-Sep-2017" "" "bst source-bundle Manual"
+.TH "BST SOURCE-BUNDLE" "1" "19-Feb-2018" "" "bst source-bundle Manual"
 .SH NAME
 bst\-source-bundle \- Produce a build bundle to be manually executed
 .SH SYNOPSIS
@@ -8,7 +8,7 @@ bst\-source-bundle \- Produce a build bundle to be manually executed
 Produce a source bundle to be manually executed
 .SH OPTIONS
 .TP
-\fB\-\-except\fP TEXT
+\fB\-\-except\fP PATH
 Elements to except from the tarball
 .TP
 \fB\-\-compression\fP [none|gz|bz2|xz]
@@ -17,9 +17,6 @@ Compress the tar file using the given algorithm.
 \fB\-\-track\fP
 Track new source references before building
 .TP
-\fB\-\-variant\fP TEXT
-A variant of the specified target
-.TP
 \fB\-f,\fP \-\-force
 Overwrite files existing in checkout directory
 .TP
diff --git a/man/bst-track.1 b/man/bst-track.1
index 3c6f96369..c65c7a229 100644
--- a/man/bst-track.1
+++ b/man/bst-track.1
@@ -1,9 +1,9 @@
-.TH "BST TRACK" "1" "10-Sep-2017" "" "bst track Manual"
+.TH "BST TRACK" "1" "19-Feb-2018" "" "bst track Manual"
 .SH NAME
 bst\-track \- Track new source references
 .SH SYNOPSIS
 .B bst track
-[OPTIONS] TARGET
+[OPTIONS] [ELEMENTS]...
 .SH DESCRIPTION
 Consults the specified tracking branches for new versions available
 to build and updates the project with any newly available references.
@@ -18,11 +18,8 @@ Specify `--deps` to control which sources to track:
     all:   All dependencies
 .SH OPTIONS
 .TP
-\fB\-\-except\fP TEXT
+\fB\-\-except\fP PATH
 Except certain dependencies from tracking
 .TP
 \fB\-d,\fP \-\-deps [none|all]
-The dependencies to track (default: none)
-.TP
-\fB\-\-variant\fP TEXT
-A variant of the specified target
\ No newline at end of file
+The dependencies to track (default: none)
\ No newline at end of file
diff --git a/man/bst-workspace-close.1 b/man/bst-workspace-close.1
index 8d889c3a6..af00b3ab2 100644
--- a/man/bst-workspace-close.1
+++ b/man/bst-workspace-close.1
@@ -1,4 +1,4 @@
-.TH "BST WORKSPACE CLOSE" "1" "10-Sep-2017" "" "bst workspace close Manual"
+.TH "BST WORKSPACE CLOSE" "1" "19-Feb-2018" "" "bst workspace close Manual"
 .SH NAME
 bst\-workspace\-close \- Close a workspace
 .SH SYNOPSIS
@@ -8,11 +8,5 @@ bst\-workspace\-close \- Close a workspace
 Close a workspace
 .SH OPTIONS
 .TP
-\fB\-s,\fP \-\-source INDEX
-The source of the workspace to remove. Projects with one source may omit this
-.TP
 \fB\-\-remove\-dir\fP
-Remove the path that contains the closed workspace
-.TP
-\fB\-\-variant\fP TEXT
-A variant of the specified target
\ No newline at end of file
+Remove the path that contains the closed workspace
\ No newline at end of file
diff --git a/man/bst-workspace-list.1 b/man/bst-workspace-list.1
index e44a4968a..ebb2930e0 100644
--- a/man/bst-workspace-list.1
+++ b/man/bst-workspace-list.1
@@ -1,4 +1,4 @@
-.TH "BST WORKSPACE LIST" "1" "10-Sep-2017" "" "bst workspace list Manual"
+.TH "BST WORKSPACE LIST" "1" "19-Feb-2018" "" "bst workspace list Manual"
 .SH NAME
 bst\-workspace\-list \- List open workspaces
 .SH SYNOPSIS
diff --git a/man/bst-workspace-open.1 b/man/bst-workspace-open.1
index 35a4731ff..0620a4e94 100644
--- a/man/bst-workspace-open.1
+++ b/man/bst-workspace-open.1
@@ -1,4 +1,4 @@
-.TH "BST WORKSPACE OPEN" "1" "10-Sep-2017" "" "bst workspace open Manual"
+.TH "BST WORKSPACE OPEN" "1" "19-Feb-2018" "" "bst workspace open Manual"
 .SH NAME
 bst\-workspace\-open \- Open a new workspace
 .SH SYNOPSIS
@@ -14,11 +14,5 @@ Do not checkout the source, only link to the given directory
 \fB\-f,\fP \-\-force
 Overwrite files existing in checkout directory
 .TP
-\fB\-s,\fP \-\-source INDEX
-The source to create a workspace for. Projects with one source may omit this
-.TP
-\fB\-\-variant\fP TEXT
-A variant of the specified target
-.TP
 \fB\-\-track\fP
 Track and fetch new source references before checking out the workspace
\ No newline at end of file
diff --git a/man/bst-workspace-reset.1 b/man/bst-workspace-reset.1
index fd08bba34..6576cdd64 100644
--- a/man/bst-workspace-reset.1
+++ b/man/bst-workspace-reset.1
@@ -1,4 +1,4 @@
-.TH "BST WORKSPACE RESET" "1" "10-Sep-2017" "" "bst workspace reset Manual"
+.TH "BST WORKSPACE RESET" "1" "19-Feb-2018" "" "bst workspace reset Manual"
 .SH NAME
 bst\-workspace\-reset \- Reset a workspace to its original state
 .SH SYNOPSIS
@@ -8,14 +8,8 @@ bst\-workspace\-reset \- Reset a workspace to its original state
 Reset a workspace to its original state
 .SH OPTIONS
 .TP
-\fB\-s,\fP \-\-source INDEX
-The source of the workspace to reset. Projects with one source may omit this
-.TP
 \fB\-\-track\fP
 Track and fetch the latest source before resetting
 .TP
 \fB\-\-no\-checkout\fP
-Do not checkout the source, only link to the given directory
-.TP
-\fB\-\-variant\fP TEXT
-A variant of the specified target
\ No newline at end of file
+Do not checkout the source, only link to the given directory
\ No newline at end of file
diff --git a/man/bst-workspace.1 b/man/bst-workspace.1
index faf61b914..c40d4fca1 100644
--- a/man/bst-workspace.1
+++ b/man/bst-workspace.1
@@ -1,4 +1,4 @@
-.TH "BST WORKSPACE" "1" "10-Sep-2017" "" "bst workspace Manual"
+.TH "BST WORKSPACE" "1" "19-Feb-2018" "" "bst workspace Manual"
 .SH NAME
 bst\-workspace \- Manipulate developer workspaces
 .SH SYNOPSIS
@@ -8,21 +8,21 @@ bst\-workspace \- Manipulate developer workspaces
 Manipulate developer workspaces
 .SH COMMANDS
 .PP
-\fBopen\fP
-  Open a new workspace
-  See \fBbst workspace-open(1)\fP for full documentation on the \fBopen\fP command.
-
-.PP
 \fBlist\fP
   List open workspaces
   See \fBbst workspace-list(1)\fP for full documentation on the \fBlist\fP command.
 
 .PP
+\fBreset\fP
+  Reset a workspace to its original state
+  See \fBbst workspace-reset(1)\fP for full documentation on the \fBreset\fP command.
+
+.PP
 \fBclose\fP
   Close a workspace
   See \fBbst workspace-close(1)\fP for full documentation on the \fBclose\fP command.
 
 .PP
-\fBreset\fP
-  Reset a workspace to its original state
-  See \fBbst workspace-reset(1)\fP for full documentation on the \fBreset\fP command.
+\fBopen\fP
+  Open a new workspace
+  See \fBbst workspace-open(1)\fP for full documentation on the \fBopen\fP command.
diff --git a/man/bst.1 b/man/bst.1
index 783b74af0..c0d1da1db 100644
--- a/man/bst.1
+++ b/man/bst.1
@@ -1,4 +1,4 @@
-.TH "BST" "1" "10-Sep-2017" "" "bst Manual"
+.TH "BST" "1" "19-Feb-2018" "" "bst Manual"
 .SH NAME
 bst \- Build and manipulate BuildStream projects...
 .SH SYNOPSIS
@@ -56,34 +56,13 @@ A file to store the main log (allows storing the main log while in interactive m
 \fB\-\-colors\fP / \-\-no\-colors
 Force enable/disable ANSI color codes in output
 .TP
-\fB\-a,\fP \-\-arch TEXT
-Machine architecture (default: x86_64)
-.TP
-\fB\-\-host\-arch\fP TEXT
-Machine architecture for the sandbox (defaults to --arch)
-.TP
-\fB\-\-target\-arch\fP TEXT
-Machine architecture for build output (defaults to --arch)
-.TP
 \fB\-\-strict\fP / \-\-no\-strict
 Elements must be rebuilt when their dependencies have changed
+.TP
+\fB\-o,\fP \-\-option <TEXT TEXT>...
+Specify a project option
 .SH COMMANDS
 .PP
-\fBbuild\fP
-  Build elements in a pipeline
-  See \fBbst-build(1)\fP for full documentation on the \fBbuild\fP command.
-
-.PP
-\fBshell\fP
-  Shell into an element's sandbox environment
-  See \fBbst-shell(1)\fP for full documentation on the \fBshell\fP command.
-
-.PP
-\fBcheckout\fP
-  Checkout a built artifact
-  See \fBbst-checkout(1)\fP for full documentation on the \fBcheckout\fP command.
-
-.PP
 \fBfetch\fP
   Fetch sources in a pipeline
   See \fBbst-fetch(1)\fP for full documentation on the \fBfetch\fP command.
@@ -94,14 +73,14 @@ Elements must be rebuilt when their dependencies have changed
   See \fBbst-workspace(1)\fP for full documentation on the \fBworkspace\fP command.
 
 .PP
-\fBpull\fP
-  Pull a built artifact
-  See \fBbst-pull(1)\fP for full documentation on the \fBpull\fP command.
+\fBtrack\fP
+  Track new source references
+  See \fBbst-track(1)\fP for full documentation on the \fBtrack\fP command.
 
 .PP
-\fBshow\fP
-  Show elements in the pipeline
-  See \fBbst-show(1)\fP for full documentation on the \fBshow\fP command.
+\fBcheckout\fP
+  Checkout a built artifact
+  See \fBbst-checkout(1)\fP for full documentation on the \fBcheckout\fP command.
 
 .PP
 \fBsource-bundle\fP
@@ -109,11 +88,26 @@ Elements must be rebuilt when their dependencies have changed
   See \fBbst-source-bundle(1)\fP for full documentation on the \fBsource-bundle\fP command.
 
 .PP
+\fBbuild\fP
+  Build elements in a pipeline
+  See \fBbst-build(1)\fP for full documentation on the \fBbuild\fP command.
+
+.PP
+\fBshell\fP
+  Shell into an element's sandbox environment
+  See \fBbst-shell(1)\fP for full documentation on the \fBshell\fP command.
+
+.PP
 \fBpush\fP
   Push a built artifact
   See \fBbst-push(1)\fP for full documentation on the \fBpush\fP command.
 
 .PP
-\fBtrack\fP
-  Track new source references
-  See \fBbst-track(1)\fP for full documentation on the \fBtrack\fP command.
+\fBshow\fP
+  Show elements in the pipeline
+  See \fBbst-show(1)\fP for full documentation on the \fBshow\fP command.
+
+.PP
+\fBpull\fP
+  Pull a built artifact
+  See \fBbst-pull(1)\fP for full documentation on the \fBpull\fP command.