Permalink
Browse files

Add --linewise and its rationale to the docs.

Totally forgot to do this re: #19, whoops.
  • Loading branch information...
bitprophet committed Oct 24, 2011
1 parent 7c51ffe commit fbc5622fa61373a30fee46cc59a307e5c5f92e78
Showing with 45 additions and 0 deletions.
  1. +15 −0 docs/usage/env.rst
  2. +6 −0 docs/usage/fab.rst
  3. +24 −0 docs/usage/parallel.rst
View
@@ -286,6 +286,21 @@ set/appended to with :option:`-i`.
.. seealso:: `Paramiko's documentation for SSHClient.connect() <http://www.lag.net/paramiko/docs/paramiko.SSHClient-class.html#connect>`_
+.. _env-linewise:
+
+``linewise``
+------------
+
+**Default:** ``False``
+
+Forces buffering by line instead of by character/byte, typically when running
+in parallel mode. May be activated via :option:`--linewise`.
+
+.. seealso:: :ref:`linewise-output`
+
+.. versionadded:: 1.3
+
+
.. _local-user:
``local_user``
View
@@ -174,6 +174,12 @@ below.
.. versionadded:: 1.1
+.. cmdoption:: --linewise
+
+ Forces output to be buffered line-by-line instead of byte-by-byte. Often useful or required for :ref:`parallel execution <linewise-output>`.
+
+ .. versionadded:: 1.3
+
.. cmdoption:: -l, --list
Imports a fabfile as normal, but then prints a list of all discovered tasks
View
@@ -143,3 +143,27 @@ For example, to run on 5 hosts at a time::
Or skip the ``pool_size`` kwarg and instead::
$ fab -P -z 5 heavy_task
+
+.. _linewise-output:
+
+Linewise vs bytewise output
+===========================
+
+Fabric's default mode of printing to the terminal is byte-by-byte, in order to
+support :doc:`/usage/interactivity`. This often gives poor results when running
+in parallel mode, as the multiple processes may write to your terminal's
+standard out stream simultaneously.
+
+To help offset this problem, you may set :ref:`env.linewise <env-linewise>` to
+``True`` or specify :option:`--linewise`. This will cause you to lose most of
+the benefits outlined in the above link Fabric's remote interactivity features,
+but as those do not map well to parallel invocations, it's typically a fair
+trade.
+
+There's no way to avoid the multiple processes mixing up on a line-by-line
+basis, but you will at least be able to tell them apart by the host-string line
+prefix.
+
+.. note::
+ Future versions will add improved logging support to make troubleshooting
+ parallel runs easier.

0 comments on commit fbc5622

Please sign in to comment.