shelly
shell-like (systems) programming in Haskell
https://github.com/gregwebs/Shelly.hs
Version on this page: | 1.12.1 |
LTS Haskell 22.33: | 1.12.1@rev:1 |
Stackage Nightly 2024-09-07: | 1.12.1@rev:1 |
Latest on Hackage: | 1.12.1@rev:1 |
shelly-1.12.1@sha256:a5fcf2a81ad6953aa5c8d5ccab82a3c47d9ac848316d607c696c190df1454039,5451
Module documentation for 1.12.1
Shelly
Shelly provides a single module for convenient systems programming in Haskell.
- Shelly is aimed at convenience and getting things done rather than being a demonstration of elegance.
- It has detailed and useful error messages.
- It maintains its own environment, making it thread-safe.
- It has low memory usage: It has
run_
and other underscore variants that do not return stdout,runFoldLines
to run a fold operation over each line rather than loading all of stdout into memory,runHandle
andrunHandles
for complete control over handles.
The focus of this library on convenience combined with good error messages should make shelly approachable for newer users of Haskell.
More shelly packages
The shelly-extra package has some additional functionality that requires additional dependencies, currently including a convenient concurrency/futures implementation.
Examples
- A small deployment script
- Yesod development installer
- cabal-meta, a haskell install tool
- antigen-hs, a zsh plugin manager
Blog Posts
Testimonials
Help
Alternatives
Haskell shell scripting libraries
- HSH: A good alternative if you want to mixup usage of
String
andByteString
rather than just useText
. - HsShellScript: Has extensive low-level shell capabilities.
- shell-conduit: Efficient streaming via conduits. Makes some portability sacrifices by
- encouraging one to just use the shell instead of cross-platform Haskell code, and
- encouraging one to use a convenience function that searches the
PATH
at compile-time.
- shell-monad: Compile Haskell code down to shell script. This is a different approach from all the rest of the libraries. Writing your script is not as user-friendly as the other Haskell libraries, but it nicely solves the deployment issue.
- shh: Shell-like syntax with native piping. Can be used from GHCi as an interactive shell replacement.
- turtle: In some sense a redesign of Shelly designed for beginner-friendliness.
HSH, HsShellScript and shh (unlike Shelly currently) implement very efficient mechanisms for piping/redirecting in the system. turtle, like Shelly offers folding as a way to efficiently deal with a stream.
None of the alternatives to Shelly offer command tracing. For some this is an absolutely critical feature, particularly given that Haskell does not yet offer up stack traces.
Haskell file-finding supplements
- find-conduit: Uses conduits, similar speed to GNU find.
- FileManip: Uses Lazy IO.
Shelly’s finders load all files into memory. This is simpler to use if you control the filesystem structure and know the system is bounded in size. However, if the filesystem structure is unbounded it consumes unbounded memory.
Shell commands with richer input/output
Shelly does not change the nature of shell scripting (text in, text out). If you want something more revolutionary you might try these:
- PowerShell is probably the best known.
- A Haskell project using typed JSON.
- RecordStream using untyped JSON.
Usage
Shelly’s main goal is ease of use. There should be a primitive for every shell operation you need so you can easily build abstractions, so there are many of the usual file and environment operations.
There are 2 main entry points for running arbitrary commands: run
and cmd
.
They take a FilePath as their first argument. run
takes a [Text]
as its second argument.
cmd
takes a variadic number of arguments, and they can be either Text
or FilePath
.
Fun Example: shows an infectious script: it uploads itself to a server and runs itself over ssh
.
Of course, the development machine may need to be exactly the same OS as the server.
I recommend using the boilerplate at the top of this example in your projects. This includes setting line buffering if you are dealing with text and not binary data.
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE ExtendedDefaultRules #-}
{-# OPTIONS_GHC -fno-warn-type-defaults #-}
import Shelly
import System.IO
import Data.Text as T
default (T.Text)
main :: IO ()
main = do
hSetBuffering stdout LineBuffering
shelly $ verbosely $ do
host <- run "uname" ["-n"]
if T.stripEnd host == "local-machine"
then do d <- cmd "date"
c <- escaping False $ cmd "git" "log -1 | head -1 | awk '{print $2}'"
appendfile "log/deploy.log" $ T.intercalate " - " [T.stripEnd d, c]
uploads "my-server:/remote/path/" ["deploy"]
sshPairs_ "my-server" [("cd", ["/remote/path"]), ("./deploy", [])]
else do
cmd "./script/angel"
-- same path on remote host
-- will create directories
uploads :: Text -> [Text] -> Sh ()
uploads remote locals = rsync $ ["--relative"] ++ locals ++ [remote]
rsync :: [Text] -> Sh ()
rsync args = run_ "rsync" $ ["--delete", "-avz", "--no-g"] ++ args
Variadic arguments to cmd
Yes, as seen above you can write variadic functions in Haskell quite easily, you just can’t compose them as easily.
I find cmd
to be more convenient, but I often use run
and command
variants when I am building up abstractions.
Building up abstractions with cmd will require type signatures.
-- easy signature, but only allows one argument
let cabal = cmd "cabal" :: Text -> Sh Text
-- more complex signature that allows partial application of cmd
let cabal = cmd "cabal" :: Shelly.ShellCmd result => result
Escaping
By default, all commands are shell escaped.
If you want the shell to interpret special characters such as *
, just use escaping False $ do ...
.
Using Text and FilePath together
Shelly’s usage of Text
means you may need to convert between Text
and FilePath
sometimes.
This should be infrequent though because:
cmd
will convertFilePath
toText
.- The
</>
and<.>
combinators convertText
into aFilePath
automatically.
Manual conversion is done through toTextIgnore
or toTextWarn
.
Thread-safe working directory and relative paths
Command cd
does not change the process working directory (essentially a global variable),
but instead changes the shelly state (which is thread safe).
All of the Shelly API takes this into account, internally shelly converts all paths to absolute paths. You can turn a relative path into an absolute with absPath
or canonic
or you can make a path relative to the Shelly working directory with relPath
.
Good error messages
Haskell’s #1 weakness for IO code is a lack of stack traces.
Shelly gives you something different: detailed logging.
In most cases this should be more useful than a stack trace.
Shelly keeps a log of API usage and saves it to a .shelly
directory on failure.
If you use shellyNoDir
, the log will instead be printed to stderr
.
This is in addition to the verbosely
settings that will print out commands and their output as the program is running.
Shelly’s own error messages are detailed and in some cases it will catch Haskell exceptions and re-throw them with better messages.
If you make your own primitive functions that do not use the existing Shelly API, you can create a wrapper in the Sh monad that use trace
or tag
to log what they are doing.
You can turn tracing off (not generally recommended) by setting tracing False
.
Changes
1.12.1
Andreas Abel, 2023-04-03
- Add
print_commands_with
andechoWith
which can be used to override the default printing functions (e.g. to add color). (Chris Wendt, PR #228.) - Tested with GHC 8.2 - 9.6 (cabal) and GHC 8.10 - 9.6 (stack).
1.12.0.1
Andreas Abel, 2023-04-02
- Make
show_command
more robust to special characters and only quote when necessary. (Chris Wendt, PR #229.) - Tested with GHC 8.2 - 9.6 (cabal) and GHC 8.10 - 9.6 (stack).
1.12.0
Andreas Abel, 2023-02-27
-
Rework
ShellCmd
andShellCommand
instances to supportString
arguments: Issue #143 fixed by Cunning Defenstrator in PR #221.This involves a breaking change in classes
CmdArg
andShellArg
: MethodtoTextArg
has been replaced bytoTextArgs
.Sample migration:
#if MIN_VERSION_shelly(1,12,0) -- new import Shelly (toTextArgs) snoc opts arg = opts ++ toTextArgs arg #else -- old import Shelly (toTextArg) snoc opts arg = opts ++ [ toTextArg arg ] #endif
-
Dropped GHC 8.0 to get rid of deprecated
LANGUAGE IncoherentInstances
. -
Builds with GHC 8.2 - 9.6.
1.11.0
Andreas Abel, 2023-01-24
- Restore running of local scripts, e.g.
cmd "./foo.sh"
: Issue #107 fixed by Alfredo di Napoli in PR #216. - Builds with GHC 8.0 - 9.4.
1.10.0.1
Andreas Abel, 2023-01-24
- Allow
unix-compat-0.6
. - Builds
-Wall
warning-free with GHC 8.0 - 9.4.
1.10.0
Andreas Abel, 2022-01-30
- Allow
transformers-0.6
:- Replace
ErrorT
byExceptT
. - Remove
MonadSh
andMonadShControl
instance forListT
. #211
- Replace
- Bump lower bounds of dependencies, keeping all versions that build with GHC >= 8.0.
- Remove unused
unix
dependency. - Allow
time-1.12
. - Builds warning-free with GHC 8.0 - 9.2.1.
1.9.0
Greg Weber, 2019-08-29
- Drop dependencies
system-fileio
andsystem-filepath
in favor offilepath
: TheFilePath
type changed to a synonym ofString
. - Allow
time >= 1.9
. - Builds with GHC >= 8.0 (tested up to 9.2).
1.8.1
Greg Weber, 2018-05-30
- New function
cp_should_follow_symlinks
to specify whether a copy should follow symlinks.
1.8.0
Greg Weber, 2018-05-09
cp_r
now uses upper case R:cp -R
.
1.7.2
Greg Weber, 2018-03-17
- Fix handling of case-insensitive environment variables on Windows. #166
1.7.1
Greg Weber, 2018-03-06
- Support
exceptions-0.9
.
1.7.0.1
Greg Weber, 2018-01-23
1.7.0
Greg Weber, 2017-12-10
- Quote
ssh
remote commands aggressively with single quotes. #160
1.6.9
Greg Weber, 2017-12-07
- Strongly escape
ssh
commands. - Add
sshPairsP
: parallel execution ofssh
commands.
1.6.8.7
Sibi Prabakaran, 2017-11-26
- Relax
unix-compat
constraints.
1.6.8.6
Sibi Prabakaran, 2017-11-19
- Fix Build issue #156
1.6.8.5
Sibi Prabakaran, 2017-11-12
- Fix Windows build #155
1.6.8.4
Greg Weber, 2017-08-07
- Option
followSymlink
for find-command. - Allow
time-1.7/8
.
1.6.8.3
Greg Weber, 2017-03-03
- Support GHC 8.0.2
1.6.8.2
Greg Weber, 2017-03-03
- Allow
time-1.6
anddirectory-1.3
1.6.8.1
Greg Weber, 2016-10-02
- changelog missing
1.6.8
Greg Weber, 2016-06-26
- Added
sshPairsWithOptions
function.
1.6.7
Greg Weber, 2016-06-24
- Flush
stdout
when usingecho
, not justecho_n
. - Fix should be able to silence
stderr
when usingrunHandle
. - Expose
RunFailed
.
1.6.6
Greg Weber, 2016-04-21
- Add
prependToPath
function.
1.6.5
Greg Weber, 2015-12-10
- Expose
MonadShControl
.
1.6.4.1
Greg Weber, 2015-12-01
- Add
writeBinary
function.