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...
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 PATH
.
More about configuration is mentioned later.
- Install Go (used Go 1.3.3, but any Go 1.x should do the trick).
- Set up a Go workspace.
- Add the
bin
directory of your workspace toPATH
. - Run
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 usegit clone
directly... - Run
go get github.com/tools/godep
to installgodep
, which handles vendoring. - Run
make godep-install
in the project directory, which puts the resulting binaries into thebin
directory of the workspace. - Run
salsaflow
to make sure everything went well.
To use SalsaFlow, you will also need
git
version1.9.x
or newer in yourPATH
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 develop
docs):
- cherry-pick
- 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
- 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
into
.salsaflow
directory 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 $HOME/.salsaflow.json
.
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 -config
.
SalsaFlow looks for the local cofiguration file in $REPO_ROOT/.salsaflow/config.json
.
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 .salsaflow/scripts
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 scripts
directory is actually <script-name>_<platform>.<runner>
where
<script-name>
is the name as mentioned above, e.g.get_version
.<platform>
can be any valid value for Go'sruntime.GOOS
, e.g.windows
,linux
,darwin
and so on. You can also useunix
to 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 bebash
(Bash),js
(Node.js),bat
(cmd.exe) orps1
(PowerShell.exe). Naturally, only some combinations make sense, e.g. you cannot run PowerShell on Mac OS X, so a script calledget_version_darwin.ps1
would 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 LICENSE
file.