|Build status||GoDoc||Gitter IM|
SalsaFlow is your ultimate Trunk Based Development (TBD) CLI utility.
Actually, I don't know about you, but we use it here at Salsita.
SalsaFlow is written in Go. Compiling has never been that fast. No more sword fighting in the corridor, sorry...
Installing from a Package
The pre-built binaries are attached to GitHub releases for this repository.
See the latest release for yourself!
So, to use the pre-built binaries,
- download the relevant archive, then
- copy the content to a directory in your
PATH. Make sure that all the files are in the same directory.
In case you are using the pre-built binaries and you want to upgrade
you SalsaFlow to the most recent version, you case use
salsaflow pkg upgrade.
In fetches the artifacts attached to the latest GitHub release and replaces
the current executables.
In case you need to run
pkg upgrade as root, you may need to use
-config flag to tell SalsaFlow here your global configuration file is.
It is better, though, to place SalsaFlow executables in a directory that is
writable by your usual user and just add that directory into
More about configuration is mentioned later.
Installing from Sources
- Install Go (used Go 1.3.3, but any Go 1.x should do the trick).
- Set up a Go workspace.
- Add the
bindirectory of your workspace to
go get -d github.com/salsaflow/salsaflow. This will get the sources and put them into the workspace. You can as well just go and use
go get github.com/tools/godepto install
godep, which handles vendoring.
make godep-installin the project directory, which puts the resulting binaries into the
bindirectory of the workspace.
salsaflowto make sure everything went well.
Other System Requirements
To use SalsaFlow, you will also need
1.9.xor newer in your
Modules may also require some additional packages to be installed.
Well, the best thing you can do is to just run
salsaflow -h and read.
More in-depth SalsaFlow principes are explained on the wiki.
The complete list of SalsaFlow commands follows (links pointing to the
- pkg install
- pkg upgrade
- release changes
- release deploy
- release notes
- release stage
- release start
- repo bootstrap
- repo init
- repo prune
- review post
- story changes
- story open
- story start
- version bump
SalsaFlow can only be used when you are within a project repository (except the
pkg subcommands, these can be used anywhere).
The repository is automagically initialised when you run any SalsaFlow command there,
but you can also trigger the process by running
repo init. SalsaFlow uses a couple of git hooks,
which are installed during the initialisation process.
You probably want to read the following section about SalsaFlow configuration before doing anything serious since SalsaFlow will anyway refuse to do anything useful until it is configured properly.
There are two places where SalsaFlow configuration is being kept:
- The global, user-wide configuration is written into
$HOME/.salsaflow.json. This file mostly contains the data that cannot be committed, i.e. access tokens and such.
- The local, project-specific configuration is expected to be placed
.salsaflowdirectory in the repository root. This directory contains the local configuration file,
config.json, as well as some project-specific custom scripts that are to be supplied by the user and committed into
.salsaflow/scripts. More on custom scripts later.
The global, user-specific configuration file resides in
It stores module-specific configuration as a map. The exact format obviously depends
on what modules are being used.
You can use
-config flag with any command to specify the path to the
global configuration file manually. This is handy when you need to run
pkg upgrade as root using
sudo. In that case
$HOME is not pointing to the home
directory of your usual user and SalsaFlow will fail to find the right
configuration file unless told where to look for it using
SalsaFlow looks for the local cofiguration file in
The structure is similar to the global configuration file except the fact that
it also includes the list of active modules for particular module kinds.
Too see a full example, just check the SalsaFlow config for this project.
SalsaFlow occasionally needs to perform an action that depends on the project type,
e.g. to increment the version number when handling releases. These custom actions
must be configured by placing certain custom scripts into
directory in the repository.
The following scripts must be supplied:
get_version- Print the current project version to stdout and exit.
set_version- Taking the new version string as the only argument, this script is expected to set the project version string to the specified value. Make sure all new files are always staged (
git add), otherwise they won't get committed by SalsaFlow.
Now, to make the whole scripting thing cross-platform, it is possible to supply
multiple script files for every script name and run different scripts on different platforms.
So, the filename schema for the scripts that are to be placed into the
directory is actually
<script-name>is the name as mentioned above, e.g.
<platform>can be any valid value for Go's
darwinand so on. You can also use
unixto run the script on all Unixy systems.
<runner>is the file extension that defines what interpreter to use to run the script. Currently it can be
ps1(PowerShell.exe). Naturally, only some combinations make sense, e.g. you cannot run PowerShell on Mac OS X, so a script called
get_version_darwin.ps1would never be executed.
Check some examples to understand better how the whole thing works.
To get up to speed quickly,
repo bootstrap command can be used to generated the initial
configuration. The user is prompted for all necessary data, no need to edit
config files manually.
repo bootstrap can be also told to use certain GitHub repository to bootstrap the local
configuration directory. When this bootstrapping skeleton is supplied,
scripts directory of the given
repository is simply poured into the local configuration directory. This can be easily used to
share custom scripts for certain project type so that the scripts are implemented once and then
just copied around. You can check the repository
that was used to bootstrap SalsaFlow itself.
SalsaFlow interacts with various services to carry out requested actions. The only supported VCS is Git, so that part is hard-coded in SalsaFlow, but other serviced are configurable in the local configuration file, namely:
- the issue tracking module,
- the code review module, and
- the release notes module (optional).
repo bootstrap lists the available modules during repository bootstrapping.
The values actually listed depend on what modules are compiled into SalsaFlow.
You don't really need to understand much about modules unless you feel like
implement a new module for SalsaFlow. The user is prompted for all necessary
data when bootstrapping the project, which is a one-time action, and then the
active modules are simply used by SalsaFlow transparently.
MIT, see the