Navigation

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.

[Bug]#450: Improve traceback display when handling ``ImportError``s 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]#323:put forgot how to expand leading tildes in
the remote file path. This has been corrected. Thanks to Piet Delport for the
catch.

[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.

[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.

[Bug]#396:--shortlist broke after the addition of
--list-format and no longer displayed the short list format
correctly. This has been fixed.

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.

#375: The logic used to separate tasks from modules when running
fab--list incorrectly considered task classes implementing the mapping
interface to be modules, not individual tasks. This has been corrected.
Thanks to Vladimir Mihailenco for the catch.

The public API for Task mentioned use of the run()
method, but Fabric’s main execution loop had not been updated to look for and
call it, forcing users who subclassed Task to define
__call__() instead. This was an oversight and has been corrected.

#76: New-style tasks have been added. With
the addition of the task decorator and the
Task class, you can now “opt-in” and explicitly mark task
functions as tasks, and Fabric will ignore the rest. The original behavior
(now referred to as “classic” tasks) will still take
effect if no new-style tasks are found. Major thanks to Travis Swicegood for
the original implementation.

#56: Namespacing is now possible: Fabric will crawl imported module
objects looking for new-style task objects and build a dotted hierarchy
(tasks named e.g. web.deploy or db.migrations.run), allowing for
greater organization. See Namespaces for details. Thanks again to
Travis Swicegood.

#10: upload_project now allows control over the
local and remote directory paths, and has improved error handling. Thanks to
Rodrigue Alcazar for the patch.

As part of #56 (highlighted above), added --list-format to allow specification of a nested output format from --list.

#107: require‘s provided_by kwarg now
accepts iterables in addition to single values. Thanks to Thomas Ballinger
for the patch.

#117: upload_template now supports the
put flags mirror_local_mode and mode. Thanks to
Joe Stump for the suggestion and Thomas Ballinger for the patch.

#154: sed now allows customized regex flags
to be specified via a new flags parameter. Thanks to Nick Trew for the
suggestion and Morgan Goose for initial implementation.

#170: Allow exclusion of specific hosts from
the final run list. Thanks to Casey Banner for the suggestion and patch.

#189: Added --abort-on-prompts/env.abort_on_prompts to allow a more non-interactive behavior,
aborting/exiting instead of trying to prompt the running user. Thanks to
Jeremy Avnet and Matt Chisholm for the initial patch.

#273: upload_template now offers control over
whether it attempts to create backups of pre-existing destination files.
Thanks to Ales Zoulek for the suggestion and initial patch.

#283: Added the with_settings decorator to allow
application of env var settings to an entire function, as an alternative to
using the settings context manager. Thanks to
Travis Swicegood for the patch.

#115: An implementation detail causing host lists to lose order
when deduped by the fab execution loop, has been patched to preserve
order instead. So e.g. fab-Ha,b,c (or setting env.hosts=['a','b','c']) will now always run on a, then b, then c. Previously,
there was a chance the order could get mixed up during deduplication. Thanks
to Rohit Aggarwal for the report.

#345: contains returned the stdout of its
internal grep command instead of success/failure, causing incorrect
behavior when stderr exists and is combined with stdout. This has been
corrected. Thanks to Szymon Reichmann for catch and patch.

#184: Make the usage of rsync_project‘s
local_dir argument more obvious, regarding its use in the rsync call.
(Specifically, so users know they can pass in multiple, space-joined
directory names instead of just one single directory.)

#258: Bugfix to a previous, incorrectly applied fix regarding
local on Windows platforms.

#324: Update run/sudo‘s
combine_stderr kwarg so that it correctly overrides the global setting in
all cases. This required changing its default value to None, but the
default behavior (behaving as if the setting were True) has not changed.
Thanks to Matthew Woodcraft and Connor Smith for the catch.

#352 (also #320): Seemingly random issues with output lockup
and input problems (e.g. sudo prompts incorrectly rejecting passwords) appear
to have been caused by an I/O race condition. This has been fixed. Thanks to
Max Arnold and Paul Oswald for the detailed reports and to Max for the
diagnosis and patch.

#301: Fixed a bug in local‘s behavior when
capture=False and output.stdout (or .stderr) was also False.
Thanks to Chris Rose for the catch.

#310: Update edge case in put where using the
mode kwarg alongside use_sudo=True runs a hidden
sudo command. The mode kwarg needs to be octal but
was being interpolated in the sudo call as a string/integer. Thanks to
Adam Ernst for the catch and suggested fix.

#311: append was supposed to have its
partial kwarg’s default flipped from True to False. However, only
the documentation was altered. This has been fixed. Thanks to Adam Ernst for
bringing it to our attention.

#312: Tweak internal I/O related loops to prevent high CPU usage and
poor screen-printing behavior on some systems. Thanks to Kirill Pinchuk for
the initial patch.

#320: Some users reported problems with dropped input, particularly
while entering sudo passwords. This was fixed via the
same change as for #312.

#7: run/sudo now allow full
interactivity with the remote end. You can interact with remote prompts and
similar interfaces, making certain tasks much easier, and freeing you from
the need to find noninteractive solutions if you don’t want to. See
Interaction with remote programs for more on these changes.

put and get received many updates,
including but not limited to: recursion, globbing, inline sudo
capability, and increased control over local file paths. See the individual
ticket line-items below for details. Erich Heine (sophacles on IRC)
played a large part in implementing and/or collecting these changes and
deserves much of the credit.

Added functionality for loading fabfiles which are Python packages
(directories) instead of just modules (single files). This allows for easier
organization of nontrivial fabfiles and paves the way for task namespacing
in the near future. See Fabfile discovery for details.

#185: Mostly of interest to those contributing to Fabric itself,
Fabric now leverages Paramiko to provide a stub SSH and SFTP server for use
during runs of our test suite. This makes quick, configurable full-stack
testing of Fabric (and, to an extent, user fabfiles) possible.

The below changes are backwards incompatible and have the potential to
break your 0.9.x based fabfiles!

contains and append
previously had the filename argument in the second position, whereas all
other functions in the contrib.files module had
filename as the first argument. These two functions have been brought in
line with the rest of the module.

sed now escapes single-quotes and parentheses in
addition to forward slashes, in its before and after kwargs. Related
to, but not entirely contained within, #159.

The user and pty kwargs in sudo‘s signature have
had their order swapped around to more closely match
run.

As part of the changes made in #7, run and
sudo have had the default value of their pty kwargs
changed from False to True. This, plus the addition of the
combine_stderr kwarg/env var, may result in significant behavioral
changes in remote programs which operate differently when attached to a tty.

#61: put and get now honor
the remote current-working-directory changes applied by
cd. Previously they would always treat relative
remote paths as being relative to the remote home directory.

#79: get now allows increased control over local
filenames when downloading single or multiple files. This is backwards
incompatible because the default path/filename for downloaded files has
changed. Thanks to Juha Mustonen, Erich Heine and Max Arnold for
brainstorming solutions.

#88: local has changed the default value of its
capture kwarg, from True to False. This was changed in order to
be more intuitive, at the cost of no longer defaulting to the same rich
return value as in run/sudo (which
is still available by specifying capture=True.)

#121: put will no longer automatically attempt
to mirror local file modes. Instead, you’ll need to specify
mirror_local_mode=True to get this behavior. Thanks to Paul Smith for a
patch covering part of this change.

#172: append has changed the default value of
its partial kwarg from True to False in order to be safer/more
intuitive.

Prerelease versions of Fabric (starting with the 1.0 prereleases) will now
print the Git SHA1 hash of the current checkout, if the user is working off
of a Git clone of the Fabric source code repository.

#55: run, sudo and
local now provide access to their standard error
(stderr) as an attribute on the return value, alongside e.g. .failed.

#148: local now returns the same “rich” string
object as run/sudo do, so that it
is a string containing the command’s stdout (if capture=True) or the
empty string (if capture=False) which exposes the .failed and
.return_code attributes, and so forth.

#151: Added a puts utility function, which allows
greater control over fabfile-generated (as opposed to Fabric-generated)
output. Also added fastprint, an alias to
puts allowing for convenient unbuffered,
non-newline-terminated printing.

#193: When requesting a remote pseudo-terminal, use the invoking
terminal’s dimensions instead of going with the default.

#217: get/put now accept
file-like objects as well as local file paths for their local_path
arguments.

#245: Added the lcd context manager for
controlling local‘s current working directory and
put/get‘s local working
directories.

#274: put/get now have
return values which may be iterated over to access the paths of files
uploaded remotely or downloaded locally, respectively. These return values
also allow access to .failed and .succeeded attributes, just like
run and friends. (In this case, .failed is actually
a list itself containing any paths which failed to transfer, which naturally
acts as a boolean as well.)

#268: Allow for @ symbols in usernames, which is valid on some
systems. Fabric’s host-string parser now splits username and hostname at the
last @ found instead of the first. Thanks to Thadeus Burgess for the
report.

#52: Full tracebacks during aborts are now displayed if the user has
opted to see debug-level output.

#101: Added colors module with basic color output support.
(#101 is still open: we plan to leverage the new module in Fabric’s
own output in the future.)

#137: Commas used to separate per-task arguments may now be escaped
with a backslash. Thanks to Erich Heine for the patch.

#144: hosts (and roles)
will now expand a single, iterable argument instead of requiring one to use
e.g. @hosts(*iterable).

#151: Added a puts utility function, which allows
greater control over fabfile-generated (as opposed to Fabric-generated)
output. Also added fastprint, an alias to
puts allowing for convenient unbuffered,
non-newline-terminated printing.

#208: Users rolling their own shell completion or who otherwise find
themselves performing text manipulation on the output of --list may now use --shortlist to get a plain, newline-separated
list of task names.

#86, #158: Removed the bundled Paramiko 1.7.4 and updated the
setup.py to require Paramiko >=1.7.6. This lets us skip the known-buggy
Paramiko 1.7.5 while getting some much needed bugfixes in Paramiko 1.7.6.

#82: append now offers a partial kwarg
allowing control over whether the “don’t append if given text already exists”
test looks for exact matches or not. Thanks to Jonas Nockert for the catch
and discussion.

#112: fab--list now prints out the fabfile’s module-level
docstring as a header, if there is one.

#75: fab, when called with no arguments or (useful) options, now
prints help, even when no fabfile can be found. Previously, calling fab
in a location with no fabfile would complain about the lack of fabfile
instead of displaying help.

#130: Context managers now correctly clean up env if they
encounter an exception. Thanks to Carl Meyer for catch + patch.

#132: local now calls strip on its stdout,
matching the behavior of run/sudo.
Thanks to Carl Meyer again on this one.

#166: cd now correctly overwrites
env.cwd when given an absolute path, instead of naively appending its
argument to env.cwd‘s previous value.

A number of small to medium documentation tweaks were made which had no
specific Redmine ticket. The largest of these is the addition of the
FAQ to the Sphinx documentation instead of storing it as a
source-only text file. (Said FAQ was also slightly expanded with new FAQs.)

#17: Added note to FAQ re: use of dtach as
alternative to screen. Thanks to Erich Heine for the tip.

#64: Updated installation docs to clarify where
package maintainers should be downloading tarballs from. Thanks to James
Pearson for providing the necessary perspective.

#95: Added a link to a given version’s changelog on the PyPI page
(technically, to the setup.pylong_description field).

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 may, if you wish, use fromfabric.apiimport*, though this is
technically not Python best practices; or you may import directly from the
Fabric submodules (e.g. fromfabric.decoratorsimporthosts.)
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:

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.

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.:

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 fabshell 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 fromfabric.fooimportbar 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 gitshortlog0.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.

Various minor tweaks to the (still in-progress) documentation, including one
thanks to Curt Micol.

Added a number of TODO items based on user feedback (thanks!)

Host information now available in granular form (user, host, port) in the
env dict, alongside the full user@host:port host string.

Parsing of host strings is now more lenient when examining the username
(e.g. hyphens.)