This changelog lists each bugfix, feature addition, etc in the order they were checked into Fabric’s source code repository. Published releases are bolded, dated and inserted at the appropriate points in the timeline.
To find out the changes included in a given release, simply look at the entries between that release and the previous one from the same release line (e.g. 1.1.4 down through 1.1.3 would be the effective changelog for the 1.1.4 release.)
Bugfixes to older release lines are always forward-ported to newer releases, and this is reflected in the changelog. Thus, the changelog for e.g. 1.2.2 might contain entries for the 1.1 and 1.0 lines as well, because those changes would have also been included in the 1.2 line.
2013-07-26: released Fabric 1.6.2
[Feature] #925: Added contrib.files.is_link. Thanks to @jtangas for the patch.
[Feature] #922: Task argument strings are now displayed when using :cmdopt:`fab -d <-d>`. Thanks to Kevin Qiu for the patch.
[Bug] #912: Leaving template_dir un-specified when using upload_template in Jinja mode used to cause 'NoneType' has no attribute 'startswith' errors. This has been fixed. Thanks to Erick Yellott for catch & to Erick Yellott + Kevin Williams for patches.
[Feature] #924: Add new env var option colorize_errors to enable coloring errors and warnings. Thanks to Aaron Meurer for the patch.
[Bug] #593: Non-ASCII character sets in Jinja templates rendered within upload_template would cause UnicodeDecodeError when uploaded. This has been addressed by encoding as utf-8 prior to upload. Thanks to Sébastien Fievet for the catch.
[Feature] #908: Support loading SSH keys from memory. Thanks to Caleb Groom for the patch.
[Bug] #171: Added missing cross-references from env variables documentation to corresponding command-line options. Thanks to Daniel D. Beck for the contribution.
[Bug] #884: The password cache feature was not working correctly with password-requiring SSH gateway connections. That’s fixed now. Thanks to Marco Nenciarini for the catch.
[Feature] #826: Enable sudo extraction of compressed archive via use_sudo kwarg in upload_project. Thanks to @abec for the patch.
[Bug] #694: Allow users to work around ownership issues in the default remote login directory: add temp_dir kwarg for explicit specification of which “bounce” folder to use when calling put with use_sudo=True. Thanks to Devin Bayer for the report & Dieter Plaetinck / Jesse Myers for suggesting the workaround.
[Bug] #882: Fix getting files when the remote CWD contains spaces
2013-05-23: released Fabric 1.6.1
[Bug] #868: Substantial speedup of parallel tasks by removing an unnecessary blocking timeout in the JobQueue loop. Thanks to Simo Kinnunen for the patch.
[Bug] #328: lcd was no longer being correctly applied to upload_template; this has been fixed. Thanks to Joseph Lawson for the catch.
[Feature] #812: Add use_glob option to put so users trying to upload real filenames containing glob patterns (*, [ etc) can disable the default globbing behavior. Thanks to Michael McHugh for the patch.
[Bug] #844: Allow users to disable Fabric’s auto-escaping in run/sudo. Thanks to Christian Long and Michael McHugh for the patch.
[Bug] #84: Fixed problem with missing -r flag in Mac OS X sed version.
[Bug] #870: Changes to shell env var escaping highlighted some extraneous and now damaging whitespace in with path():. This has been removed and a regression test added.
[Bug] #871: Use of string mode values in put(local, remote, mode="NNNN") would sometimes cause Unsupported operand errors. This has been fixed.
[Bug] #84: Fixed problem with missing -r flag in Mac OS X sed version. Thanks to Konrad Hałas for the patch.
[Bug] #861: Gracefully handle situations where users give a single string literal to env.hosts. Thanks to Bill Tucker for catch & patch.
[Bug] #367: Expand paths with tilde inside (contrib.files). Thanks to Konrad Hałas for catch & patch.
[Feature] #845: Downstream synchronization option implemented for rsync_project. Thanks to Antonio Barrero for the patch.
2013-03-01: released Fabric 1.6.0
2013-03-01: released Fabric 1.5.4
[Bug] #844: Account for SSH config overhaul in Paramiko 1.10 by e.g. updating treatment of IdentityFile to handle multiple values. This and related SSH config parsing changes are backwards incompatible; we are including them in this release because they do fix incorrect, off-spec behavior.
[Bug] #843: Ensure string pool_size values get run through int() before deriving final result (stdlib min() has odd behavior here...). Thanks to Chris Kastorff for the catch.
[Bug] #839: Fix bug in rsync_project where IPv6 address were not always correctly detected. Thanks to Antonio Barrero for catch & patch.
[Bug] #587: Warn instead of aborting when env.use_ssh_config is True but the configured SSH conf file doesn’t exist. This allows multi-user fabfiles to enable SSH config without causing hard stops for users lacking SSH configs. Thanks to Rodrigo Pimentel for the report.
[Feature] #821: Add remote_tunnel to allow reverse SSH tunneling (exposing locally-visible network ports to the remote end). Thanks to Giovanni Bajo for the patch.
[Feature] #823: Add env.remote_interrupt which controls whether Ctrl-C is forwarded to the remote end or is captured locally (previously, only the latter behavior was implemented). Thanks to Geert Jansen for the patch.
2013-01-28: released Fabric 1.5.3
[Bug] #806: Force strings given to getpass during password prompts to be ASCII, to prevent issues on some platforms when Unicode is encountered. Thanks to Alex Louden for the patch.
[Bug] #805: Update shell_env to play nice with Windows (7, at least) systems and local. Thanks to Fernando Macedo for the patch.
[Bug] #654: Parallel runs whose sum total of returned data was large (e.g. large return values from the task, or simply a large number of hosts in the host list) were causing frustrating hangs. This has been fixed.
[Feature] #402: Attempt to detect stale SSH sessions and reconnect when they arise. Thanks to @webengineer for the patch.
[Bug] #791: Cast reboot‘s wait parameter to a numeric type in case the caller submitted a string by mistake. Thanks to Thomas Schreiber for the patch.
[Bug] #703: Add a shell kwarg to many methods in files to help avoid conflicts with cd and similar. Thanks to @mikek for the patch.
[Feature] #730: Add env.system_known_hosts/–system-known-hosts to allow loading a user-specified system-level SSH known_hosts file. Thanks to Roy Smith for the patch.
2013-01-15: released Fabric 1.5.2
[Feature] #818: Added env.eagerly_disconnect option to help prevent pile-up of many open connections.
[Feature] #706: Added env.tasks, returning list of tasks to be executed by current fab command.
[Bug] #766: Use the variable name of a new-style fabric.tasks.Task subclass object when the object name attribute is undefined. Thanks to @todddeluca for the patch.
[Bug] #604: Fixed wrong treatment of backslashes in put operation when uploading directory tree on Windows. Thanks to Jason Coombs for the catch and @diresys & Oliver Janik for the patch. for the patch.
[Bug] #792: The newish shell_env context manager was incorrectly omitted from the fabric.api import endpoint. This has been remedied. Thanks to Vishal Rana for the catch.
[Feature] #735: Add ok_ret_codes option to env to allow alternate return codes to be treated os “ok”. Thanks to Andy Kraut for the pull request.
[Bug] #775: Shell escaping was incorrectly applied to the value of $PATH updates in our shell environment handling, causing (at the very least) local binary paths to become inoperable in certain situations. This has been fixed.
[Feature] #787: Utilize new Paramiko feature allowing us to skip the use of temporary local files when using file-like objects in get/put.
[Feature] #249: Allow specification of remote command timeout value by setting env.command_timeout. Thanks to Paul McMillan for suggestion & initial patch.
Added current host string to prompt abort error messages.
2012-11-15: released Fabric 1.5.1
[Bug] #776: Fixed serious-but-non-obvious bug in direct-tcpip driven gatewaying (e.g. that triggered by -g or env.gateway.) Should work correctly now.
[Bug] #771: Sphinx autodoc helper unwrap_tasks didn’t play nice with @task(name=xxx) in some situations. This has been fixed.
2012-11-06: released Fabric 1.5.0
2012-11-06: released Fabric 1.4.4
[Feature] #38: (also #698) Implement both SSH-level and ProxyCommand-based gatewaying for SSH traffic. (This is distinct from tunneling non-SSH traffic over the SSH connection, which is #78 and not implemented yet.)
- Thanks in no particular order to Erwin Bolwidt, Oskari Saarenmaa, Steven Noonan, Vladimir Lazarenko, Lincoln de Sousa, Valentino Volonghi, Olle Lundberg and Github user @acrish for providing the original patches to both Fabric and Paramiko.
[Feature] #684: (also #569) Update how task wraps task functions to preserve additional metadata; this allows decorated functions to play nice with Sphinx autodoc. Thanks to Jaka Hudoklin for catch & patch.
[Support] #103: (via #748) Long standing Sphinx autodoc issue requiring error-prone duplication of function signatures in our API docs has been fixed. Thanks to Alex Morega for the patch.
[Bug] #767: Fix (and add test for) regression re: having linewise output automatically activate when parallelism is in effect. Thanks to Alexander Fortin and Dustin McQuay for the bug reports.
[Bug] #736: Ensure context managers that build env vars play nice with contextlib.nested by deferring env var reference to entry time, not call time. Thanks to Matthew Tretter for catch & patch.
[Feature] #763: Add --initial-password-prompt to allow prefilling the password cache at the start of a run. Great for sudo-powered parallel runs.
[Feature] #665: (and #629) Update upload_template to have a more useful return value, namely that of its internal put call. Thanks to Miquel Torres for the catch & Rodrigue Alcazar for the patch.
[Feature] #578: Add name argument to task (docs) to allow overriding of the default “function name is task name” behavior. Thanks to Daniel Simmons for catch & patch.
[Feature] #761: Allow advanced users to parameterize fabric.main.main() to force loading of specific fabfiles.
[Bug] #749: Gracefully work around calls to fabric.version on systems lacking /bin/sh (which causes an OSError in subprocess.Popen calls.)
[Feature] #723: Add the group= argument to sudo. Thanks to Antti Kaihola for the pull request.
[Feature] #725: Updated local to allow override of which local shell is used. Thanks to Mustafa Khattab.
[Bug] #704: Fix up a bunch of Python 2.x style print statements to be forwards compatible. Thanks to Francesco Del Degan for the patch.
[Feature] #491: (also [Feature] #385:) IPv6 host string support. Thanks to Max Arnold for the patch.
[Feature] #699: Allow name attribute on file-like objects for get/put. Thanks to Peter Lyons for the pull request.
[Bug] #711: get would fail when filenames had % in their path. Thanks to John Begeman
[Bug] #702: require failed to test for “empty” values in the env keys it checks (e.g. require('a-key-whose-value-is-an-empty-list') would register a successful result instead of alerting that the value was in fact empty. This has been fixed, thanks to Rich Schumacher.
[Bug] #718: isinstance(foo, Bar) is used in main instead of type(foo) == Bar in order to fix some edge cases. Thanks to Mikhail Korobov.
[Bug] #693: Fixed edge case where abort driven failures within parallel tasks could result in a top level exception (a KeyError) regarding error handling. Thanks to Marcin Kuźmiński for the report.
[Support] #681: Fixed outdated docstring for runs_once which claimed it would get run multiple times in parallel mode. That behavior was fixed in an earlier release but the docs were not updated. Thanks to Jan Brauer for the catch.
2012-07-06: released Fabric 1.4.3
2012-07-06: released Fabric 1.3.8
[Feature] #263: Shell environment variable support for run/sudo added in the form of the shell_env context manager. Thanks to Oliver Tonnhofer for the original pull request, and to Kamil Kisiel for the final implementation.
[Feature] #669: Updates to our Windows compatibility to rely more heavily on cross-platform Python stdlib implementations. Thanks to Alexey Diyan for the patch.
[Bug] #671: reject_unknown_hosts sometimes resulted in a password prompt instead of an abort. This has been fixed. Thanks to Roy Smith for the report.
[Bug] #659: Update docs to reflect that local currently honors env.path. Thanks to @floledermann for the catch.
[Bug] #652: Show available commands when aborting on invalid command names.
[Support] #651: Added note about nesting with statements on Python 2.6+. Thanks to Jens Rantil for the patch.
[Bug] #649: Don’t swallow non-abort-driven exceptions in parallel mode. Fabric correctly printed such exceptions, and returned them from execute, but did not actually cause the child or parent processes to halt with a nonzero status. This has been fixed. execute now also honors env.warn_only so users may still opt to call it by hand and inspect the returned exceptions, instead of encountering a hard stop. Thanks to Matt Robenolt for the catch.
[Feature] #241: Add the command executed as a .command attribute to the return value of run/sudo. (Also includes a second attribute containing the “real” command executed, including the shell wrapper and any escaping.)
[Feature] #646: Allow specification of which local streams to use when run/sudo print the remote stdout/stderr, via e.g. run("command", stderr=sys.stdout).
[Support] #645: Update Sphinx docs to work well when run out of a source tarball as opposed to a Git checkout. Thanks again to @Arfrever for the catch.
[Support] #640: (also #644) Update packaging manifest so sdist tarballs include all necessary test & doc files. Thanks to Mike Gilbert and @Arfrever for catch & patch.
[Feature] #627: Added convenient quiet and warn_only keyword arguments to run/sudo which are aliases for settings(hide('everything'), warn_only=True) and settings(warn_only=True), respectively. (Also added corresponding context managers.) Useful for remote program calls which are expected to fail and/or whose output doesn’t need to be shown to users.
[Feature] #633: Allow users to turn off host list deduping by setting env.dedupe_hosts to False. This enables running the same task multiple times on a single host, which was previously not possible.
[Support] #634: Clarified that lcd does no special handling re: the user’s current working directory, and thus relative paths given to it will be relative to os.getcwd(). Thanks to @techtonik for the catch.
2012-05-07: released Fabric 1.4.2
2012-05-07: released Fabric 1.3.7
[Bug] #562: Agent forwarding would error out or freeze when multiple uses of the forwarded agent were used per remote invocation (e.g. a single run command resulting in multiple Git or SVN checkouts.) This has been fixed thanks to Steven McDonald and GitHub user @lynxis.
[Support] #626: Clarity updates to the tutorial. Thanks to GitHub user m4z for the patches.
[Bug] #625: hide/show did not correctly restore prior display settings if an exception was raised inside the block. This has been fixed.
[Bug] #624: Login password prompts did not always display the username being authenticated for. This has been fixed. Thanks to Nick Zalutskiy for catch & patch.
[Bug] #617: Fix the clean_revert behavior of settings so it doesn’t KeyError for newly created settings keys. Thanks to Chris Streeter for the catch.
[Feature] #615: Updated sudo to honor the new setting env.sudo_user as a default for its user kwarg.
[Bug] #616: Add port number to the error message displayed upon connection failures.
[Bug] #609: (and #564) Document and clean up env.sudo_prefix so it can be more easily modified by users facing uncommon use cases. Thanks to GitHub users 3point2 for the cleanup and SirScott for the documentation catch.
[Bug] #610: Change detection of env.key_filename‘s type (added as part of SSH config support in 1.4) so it supports arbitrary iterables. Thanks to Brandon Rhodes for the catch.
2012-04-04: released Fabric 1.4.1
2012-04-04: released Fabric 1.3.6
[Bug] #608: Add capture kwarg to rsync_project to aid in debugging rsync problems.
[Bug] #607: Allow local to display stdout/stderr when it warns/aborts, if it was capturing them.
[Bug] #395: Added an FAQ entry detailing how to handle init scripts which misbehave when a pseudo-tty is allocated.
[Bug] #568: execute allowed too much of its internal state changes (to variables such as env.host_string and env.parallel) to persist after execution completed; this caused a number of different incorrect behaviors. execute has been overhauled to clean up its own state changes – while preserving any state changes made by the task being executed.
[Bug] #584: upload_project did not take explicit remote directory location into account when untarring, and now uses cd to address this. Thanks to Ben Burry for the patch.
[Bug] #458: with_settings did not perfectly match settings, re: ability to inline additional context managers. This has been corrected. Thanks to Rory Geoghegan for the patch.
[Bug] #499: contrib.files.first used an outdated function signature in its wrapped exists call. This has been fixed. Thanks to Massimiliano Torromeo for catch & patch.
[Bug] #551: --list output now detects terminal window size and truncates (or doesn’t truncate) accordingly. Thanks to Horacio G. de Oro for the initial pull request.
[Bug] #572: Parallel task aborts (as oppposed to unhandled exceptions) now correctly print their abort messages instead of tracebacks, and cause the parent process to exit with the correct (nonzero) return code. Thanks to Ian Langworth for the catch.
[Bug] #306: Remote paths now use posixpath for a separator. Thanks to Jason Coombs for the patch.
2012-02-13: released Fabric 1.4.0
2012-02-13: released Fabric 1.3.5
2012-02-13: released Fabric 1.2.6
2012-02-13: released Fabric 1.1.8
[Bug] #495: Fixed documentation example showing how to subclass Task. Thanks to Brett Haydon for the catch and Mark Merritt for the patch.
[Bug] #410: Fixed a bug where using the task decorator inside/under another decorator such as hosts could cause that task to become invalid when invoked by name (due to how old-style vs new-style tasks are detected.) Thanks to Dan Colish for the initial patch.
[Feature] #559: rsync_project now allows users to append extra SSH-specific arguments to rsync‘s --rsh flag.
[Feature] #138: env.port may now be written to at fabfile module level to set a default nonstandard port number. Previously this value was read-only.
[Feature] #3: Fabric can now load a subset of SSH config functionality directly from your local ~/.ssh/config if env.use_ssh_config is set to True. See Leveraging native SSH config files for details. Thanks to Kirill Pinchuk for the initial patch.
[Feature] #12: Added the ability to try connecting multiple times to temporarily-down remote systems, instead of immediately failing. (Default behavior is still to only try once.) See env.timeout and env.connection_attempts for controlling both connection timeouts and total number of attempts. reboot has also been overhauled (but practically deprecated – see its updated docs.)
[Feature] #474: execute now allows you to access the executed task’s return values, by itself returning a dictionary whose keys are the host strings executed against.
[Bug] #487: Overhauled the regular expression escaping performed in append and contains to try and handle more corner cases. Thanks to Neilen Marais for the patch.
[Support] #532: Reorganized and cleaned up the output of fab --help.
[Feature] #8: Added --skip-bad-hosts/env.skip_bad_hosts option to allow skipping past temporarily down/unreachable hosts.
[Feature] #13: Env vars may now be set at runtime via the new --set command-line flag.
[Feature] #506: A new output alias, commands, has been added, which allows hiding remote stdout and local “running command X” output lines.
[Feature] #72: SSH agent forwarding support has made it into Fabric’s SSH library, and hooks for using it have been added (disabled by default; use -A or env.forward_agent to enable.) Thanks to Ben Davis for porting an existing Paramiko patch to ssh and providing the necessary tweak to Fabric.
2012-01-12: released Fabric 1.3.4
[Bug] #492: @parallel did not automatically trigger linewise output, as was intended. This has been fixed. Thanks to Brandon Huey for the catch.
[Bug] #510: Parallel mode is incompatible with user input, such as password/hostname prompts, and was causing cryptic Operation not supported by device errors when such prompts needed to be displayed. This behavior has been updated to cleanly and obviously abort instead.
[Bug] #494: Fixed regression bug affecting some env values such as env.port under parallel mode. Symptoms included rsync_project bailing out due to a None port value when run under @parallel. Thanks to Rob Terhaar for the report.
[Bug] #339: Don’t show imported colors members in --list output. Thanks to Nick Trew for the report.
2011-11-23: released Fabric 1.3.3
2011-11-23: released Fabric 1.2.5
2011-11-23: released Fabric 1.1.7
[Bug] #441: Specifying a task module as a task on the command line no longer blows up but presents the usual “no task by that name” error message instead. Thanks to Mitchell Hashimoto for the catch.
[Bug] #475: Allow escaping of equals signs in per-task args/kwargs.
[Bug] #450: Improve traceback display when handling ImportError for dependencies. Thanks to David Wolever for the patches.
[Bug] #446: Add QNX to list of secondary-case sed targets. Thanks to Rodrigo Madruga for the tip.
[Bug] #443: exists didn’t expand tildes; now it does. Thanks to Riccardo Magliocchetti for the patch.
[Bug] #437: with_settings now correctly preserves the wrapped function’s docstring and other attributes. Thanks to Eric Buckley for the catch and Luke Plant for the patch.
[Bug] #400: Handle corner case of systems where pwd.getpwuid raises KeyError for the user’s UID instead of returning a valid string. Thanks to Dougal Matthews for the catch.
[Bug] #397: Some poorly behaved objects in third party modules triggered exceptions during Fabric’s “classic or new-style task?” test. A fix has been added which tries to work around these.
[Bug] #341: append incorrectly failed to detect that the line(s) given already existed in files hidden to the remote user, and continued appending every time it ran. This has been fixed. Thanks to Dominique Peretti for the catch and Martin Vilcans for the patch.
[Bug] #342: Combining cd with put and its use_sudo keyword caused an unrecoverable error. This has been fixed. Thanks to Egor M for the report.
[Bug] #482: Parallel mode should imply linewise output; omission of this behavior was an oversight.
[Bug] #230: Fix regression re: combo of no fabfile & arbitrary command use. Thanks to Ali Saifee for the catch.
2011-11-07: released Fabric 1.3.2
2011-11-07: released Fabric 1.2.4
2011-11-07: released Fabric 1.1.6
[Support] #459: Update our setup.py files to note that PyCrypto released 2.4.1, which fixes the setuptools problems.
[Support] #467: (also #468, #469) Handful of documentation clarification tweaks. Thanks to Paul Hoffman for the patches.
2011-10-24: released Fabric 1.3.1
[Bug] #457: Ensured that Fabric fast-fails parallel tasks if any child processes encountered errors. Previously, multi-task invocations would continue to the 2nd, etc task when failures occurred, which does not fit with how Fabric usually behaves. Thanks to Github user sdcooke for the report and Morgan Goose for the fix.
2011-10-23: released Fabric 1.3.0
2011-10-23: released Fabric 1.2.3
2011-10-23: released Fabric 1.1.5
2011-10-23: released Fabric 1.0.5
[Support] #275: To support an edge use case of the features released in #19, and to lay the foundation for #275, we have forked Paramiko into the Python ‘ssh’ library and changed our dependency to it for Fabric 1.3 and higher. This may have implications for the more uncommon install use cases, and package maintainers, but we hope to iron out any issues as they come up.
[Bug] #323: put forgot how to expand leading tildes in the remote file path. This has been corrected. Thanks to Piet Delport for the catch.
[Feature] #21: It is now possible, using the new execute API call, to execute task objects (by reference or by name) from within other tasks or in library mode. execute honors the other tasks’ hosts/roles decorators, and also supports passing in explicit host and/or role arguments.
[Feature] #19: Tasks may now be optionally executed in parallel. Please see the parallel execution docs for details. Major thanks to Morgan Goose for the initial implementation.
[Bug] #182: During display of remote stdout/stderr, Fabric occasionally printed extraneous line prefixes (which in turn sometimes overwrote wrapped text.) This has been fixed.
[Bug] #430: Tasks decorated with runs_once printed extraneous ‘Executing...’ status lines on subsequent invocations. This is noisy at best and misleading at worst, and has been corrected. Thanks to Jacob Kaplan-Moss for the report.
2011-09-01: released Fabric 1.2.2
2011-09-01: released Fabric 1.1.4
2011-09-01: released Fabric 1.0.4
[Bug] #252: settings would silently fail to set env values for keys which did not exist outside the context manager block. It now works as expected. Thanks to Will Maier for the catch and suggested solution.
[Support] #393: Fixed a typo in an example code snippet in the task docs. Thanks to Hugo Garza for the catch.
[Bug] #396: --shortlist broke after the addition of --list-format and no longer displayed the short list format correctly. This has been fixed.
[Bug] #373: Re-added missing functionality preventing host exclusion from working correctly.
[Bug] #303: Updated terminal size detection to correctly skip over non-tty stdout, such as when running fab taskname | other_command.
2011-08-21: released Fabric 1.2.1
2011-08-21: released Fabric 1.1.3
2011-08-21: released Fabric 1.0.3
[Bug] #417: abort_on_prompts would incorrectly abort when set to True, even if both password and host were defined. This has been fixed. Thanks to Valerie Ishida for the report.
[Support] #416: Updated documentation to reflect move from Redmine to Github.
[Bug] #389: Fixed/improved error handling when Paramiko import fails. Thanks to Brian Luft for the catch.
2011-07-12: released Fabric 1.2.0
[Feature] #22: Enhanced @task to add aliasing, per-module default tasks, and control over the wrapping task class. Thanks to Travis Swicegood for the initial work and collaboration.
[Bug] #380: Improved unicode support when testing objects for being string-like. Thanks to Jiri Barton for catch & patch.
[Support] #382: Experimental overhaul of changelog formatting & process to make supporting multiple lines of development less of a hassle.
2011-07-07: released Fabric 1.1.2 (see below for details)
2011-06-24: released Fabric 1.0.2 (see below for details)
The content below this section comes from older versions of Fabric which wrote out changelogs to individual, undated files. They have been concatenated and preserved here for historical reasons, and may not be in strict chronological order.
This page lists all changes made to Fabric in its 1.1.0 release.
Note
This release also includes all applicable changes from the 1.0.2 release.
Note
This release also includes all applicable changes from the 0.9.7 release.
Note
This release also includes all applicable changes from the 0.9.5 release.
This page lists all changes made to Fabric in its 1.0.0 release.
The below changes are backwards incompatible and have the potential to break your 0.9.x based fabfiles!
The following changes were implemented in Fabric 0.9.7:
The following changes were implemented in Fabric 0.9.6:
The following changes were implemented in Fabric 0.9.5:
The following changes were implemented in Fabric 0.9.4:
The following changes were implemented in Fabric 0.9.3:
The following changes were implemented in Fabric 0.9.2:
The following changes were implemented in Fabric 0.9.1:
This document details the various backwards-incompatible changes made during Fabric’s rewrite between versions 0.1 and 0.9. The codebase has been almost completely rewritten and reorganized and an attempt has been made to remove “magical” behavior and make things more simple and Pythonic; the fab command-line component has also been redone to behave more like a typical Unix program.
You’ll want to at least skim the entire document, but the primary changes that will need to be made to one’s fabfiles are as follows:
You will need to explicitly import any and all methods or decorators used, at the top of your fabfile; they are no longer magically available. Here’s a sample fabfile that worked with 0.1 and earlier:
@hosts('a', 'b')
def my_task():
run('ls /var/www')
sudo('mkdir /var/www/newsite')
The above fabfile uses hosts, run and sudo, and so in Fabric 0.9 one simply needs to import those objects from the new API module fabric.api:
from fabric.api import hosts, run, sudo
@hosts('a', 'b')
def my_task():
run('ls /var/www')
sudo('mkdir /var/www/newsite')
You may, if you wish, use from fabric.api import *, though this is technically not Python best practices; or you may import directly from the Fabric submodules (e.g. from fabric.decorators import hosts.) See Fabfile construction and use for more information.
Fabric started out Python 2.5-only, but became largely 2.4 compatible at one point during its lifetime. Fabric is once again only compatible with Python 2.5 or newer, in order to take advantage of the various new features and functions available in that version.
With this change we’re setting an official policy to support the two most recent stable releases of the Python 2.x line, which at time of writing is 2.5 and 2.6. We feel this is a decent compromise between new features and the reality of operating system packaging concerns. Given that most users use Fabric from their workstations, which are typically more up-to-date than servers, we’re hoping this doesn’t cut out too many folks.
Finally, note that while we will not officially support a 2.4-compatible version or fork, we may provide a link to such a project if one arises.
The config object previously used to access and set internal state (including Fabric config options) has been renamed to env, but otherwise remains mostly the same (it allows both dictionary and object-attribute style access to its data.) env resides in the state submodule and is importable via fabric.api, so where before one might have seen fabfiles like this:
def my_task():
config.foo = 'bar'
one will now be explicitly importing the object like so:
from fabric.api import env
def my_task():
env.foo = 'bar'
Fabric’s default mode of use, in prior versions, was what we called “broad mode”: your tasks, as Python code, ran only once, and any calls to functions that made connections (such as run or sudo) would run once per host in the current host list. We also offered “deep mode”, in which your entire task function would run once per host.
In Fabric 0.9, this dichotomy has been removed, and “deep mode” is the method Fabric uses to perform all operations. This allows you to treat your Fabfiles much more like regular Python code, including the use of if statements and so forth, and allows operations like run to unambiguously return the output from the server.
Other modes of execution such as the old “broad mode” may return as Fabric’s internals are refactored and expanded, but for now we’ve simplified things, and deep mode made the most sense as the primary mode of use.
Because of how Fabric used to run in “broad mode” (see previous section) a special string formatting technique – the use of a bash-like dollar sign notation, e.g. "hostname: $(fab_host)" – had to be used to allow the current state of execution to be represented in one’s operations. This is no longer necessary and has been removed. Because your tasks are executed once per host, you may build strings normally (e.g. with the % operator) and refer to env.host_string, env.user and so forth.
For example, Fabric 0.1 had to insert the current username like so:
print("Your current username is $(fab_user)")
Fabric 0.9 and up simply reference env variables as normal:
print("Your current username is %s" % env.user)
As with the execution modes, a special string interpolation function or method that automatically makes use of env values may find its way back into Fabric at some point if a need becomes apparent.
In no particular order:
The Fabric config file location used to be ~/.fabric; in the interests of honoring Unix filename conventions, it’s now ~/.fabricrc.
The old config object (now env) had a getAny method which took one or more key strings as arguments, and returned the value attached to the first valid key. This method still exists but has been renamed to first.
Environment variables such as fab_host have been renamed to simply e.g. host. This looks cleaner and feels more natural, and requires less typing. Users will naturally need to be careful not to override these variables, but the same holds true for e.g. Python’s builtin methods and types already, so we felt it was worth the tradeoff.
Fabric’s version header is no longer printed every time the program runs; you should now use the standard --version/-V command-line options to print version and exit.
The old about command has been removed; other Unix programs don’t typically offer this. Users can always view the license and warranty info in their respective text files distributed with the software.
The old help command is now the typical Unix options -h/--help.
- Furthermore, there is no longer a listing of Fabric’s programming API available through the command line – those topics impact fabfile authors, not fab users (even though the former is a subset of the latter) and should stay in the documentation only.
prompt‘s primary function is now to return a value to the caller, although it may still optionally store the entered value in env as well.
prompt now considers the empty string to be valid input; this allows other functions to wrap prompt and handle “empty” input on their own terms.
In addition to the above changes, prompt has been updated to behave more obviously, as its previous behavior was confusing in a few ways:
- It will now overwrite pre-existing values in the environment dict, but will print a warning to the user if it does so.
- Additionally, (and this appeared to be undocumented) the default argument could take a callable as well as a string, and would simply set the default message to the return value if a callable was given. This seemed to add unnecessary complexity (given that users may call e.g. prompt(blah, msg, default=my_callable()) so it has been removed.
When connecting, Fabric used to use the undocumented fab_pkey env variable as a method of passing in a Paramiko PKey object to the SSH client’s connect method. This has been removed in favor of an ssh-like -i option, which allows one to specify a private key file to use; that should generally be enough for most users.
download is now get in order to match up with put (the name mismatch was due to get being the old method of getting env vars.)
The noshell argument to sudo (added late in its life to previous Fabric versions) has been renamed to shell (defaults to True, so the effective behavior remains the same) and has also been extended to the run operation.
- Additionally, the global sudo_noshell option has been renamed to use_shell and also applies to both run and sudo.
local_per_host has been removed, as it only applied to the now-removed “broad mode”.
load has been removed; Fabric is now “just Python”, so use Python’s import mechanisms in order to stitch multiple fabfiles together.
abort is no longer an “operation” per se and has been moved to fabric.utils. It is otherwise the same as before, taking a single string message, printing it to the user and then calling sys.exit(1).
rsyncproject and upload_project have been moved into fabric.contrib (specifically, fabric.contrib.project), which is intended to be a new tree of submodules for housing “extra” code which may build on top of the core Fabric operations.
invoke has been turned on its head, and is now the runs_once decorator (living in fabric.decorators). When used to decorate a function, that function will only execute one time during the lifetime of a fab run. Thus, where you might have used invoke multiple times to ensure a given command only runs once, you may now use runs_once to decorate the function and then call it multiple times in a normal fashion.
It looks like the regex behavior of the validate argument to prompt was never actually implemented. It now works as advertised.
Couldn’t think of a good reason for require to be a decorator and a function, and the function is more versatile in terms of where it may be used, so the decorator has been removed.
As things currently stand with the execution model, the depends decorator doesn’t make a lot of sense: instead, it’s safest/best to simply make “meta” commands that just call whatever chain of “real” commands you need performed for a given overarching task.
For example, instead of having command A say that it “depends on” command B, create a command C which calls A and B in the right order, e.g.:
def build():
local('make clean all')
def upload():
put('app.tgz', '/tmp/app.tgz')
run('tar xzf /tmp/app.tgz')
def symlink():
run('ln -s /srv/media/photos /var/www/app/photos')
def deploy():
build()
upload()
symlink()
Note
The execution model is still subject to change as Fabric evolves. Please don’t hesitate to email the list or the developers if you have a use case that needs something Fabric doesn’t provide right now!
Removed the old fab shell functionality, since the move to “just Python” should make vanilla python/ipython usage of Fabric much easier.
- We may add it back in later as a convenient shortcut to what basically amounts to running ipython and performing a handful of from fabric.foo import bar calls.
The undocumented fab_quiet option has been replaced by a much more granular set of output controls. For more info, see Managing output.
The below list was generated by running git shortlog 0.9a1..0.9a2 and then manually sifting through and editing the resulting commit messages. This will probably occur for the rest of the alphas and betas; we hope to use Sphinx-specific methods of documenting changes once the final release is out the door.
This is closer to being a straight dump of the Git changelog than the previous sections; apologies for the overall change in tense.
As with the previous changelog, this is also mostly a dump of the Git log. We promise that future changelogs will be more verbose :)