NAME
depst - Deployment State Manager
SYNOPSIS
depst COMMAND [DIR || NAME]
depst init # initialize depst for a project
depst add DIR # add a directory to depst tracking list
depst rm DIR # remove a directory from depst tracking list
depst make NAME # create a named template set (set of 3 files)
depst list [NAME] # dump a list of the template set (set of 3 files)
depst status [DIR] # check status of all tracked or specific directory
depst clean # reset depst state to match current files/directories
depst preinstall # set depst state so an "update" will deploy everything
depst deploy NAME # deployment of a specific action
depst verify [NAME] # verification of tracked actions or specific action
depst revert NAME # revertion of a specific action
depst redeploy NAME # deployment of a specific action
depst revdeploy NAME # revert and deployment of a specific action
depst update # automaticall deploy or revert to cause currency
depst help # display command synposis
depst man # display man page
DESCRIPTION
depst is a simple "deployment state" change management tool. I really like what Sqitch is doing, but I wanted something that worked on more than just databases. And I'm not very smart, so I wanted something really simple. (Both simple to use and simple to maintain.) Thus, depst was born.
Let's say you're working with a group of other software engineers on a particular software project using your favorite revision control system. Let's also say that you have a database that undergoes schema changes as features are developed, and you have various system activities like the installation of libraries or other applications. Then let's also say the team braches, works on stuff, shares those branches, reverts, merges, etc. And also from time to time you want to go back in time a bit so you can reproduce a bug. Maintaining the database state and the state of the system across all that activity can be problematic. depst tries to solve this in a very simple way, letting you be able to deploy, revert, and verify to any point in time in the development history.
COMMANDS
Typing just depst
should bring up the usage instructions, which include a command list. In nearly all cases, depst assumes you are calling depst from the root directory of your project. If not, it will complain.
init
To start using depst, you need to initialize your project by calling init
while in the root directory of your project. (If you are in a different directory, depst will assume that is your project's root directory.)
The initialization will result in a .depst
directory being created. You'll almost certainly want to add ".depst" to your .gitignore file or whatever.
add DIR
Once a project has been initialized, you need to tell depst what directories you want to "track". Into these tracked directories you'll place subdirectories with recognizable names, and into each subdirectory a set of 3 files: deploy, revert, and verify.
For example, let's say you have a database. So you create db
in your project's root directory. Then call depst add db
from your root directory. Inside db
, you might create the directory db/schema
. And under that directory, add the files: deploy, revert, and verify.
The deploy file contains the instructions to create the database schema. The revert file contains the instructions to revert what the deploy file did. And the verify file let's you verify the deploy file worked.
rm DIR
This removes a directory from the depst tracking list.
make NAME
This is a helper command. Given a directory you've already added, it will create the subdirectory and deploy, revert, and verify files.
# given db, creates db/schema and the 3 files
depst make db/schema
As a nice helper bit, make
will list the relative paths of the 3 new files. So if you want, you can do something like this:
vi `depst make db/schema`
list [NAME]
If provided a name of an action, it does the last step of make
. It lists out the relative paths of the 3 files, so you can do stuff like:
vi `depst list db/schema`
If not provided a name of an action, it will list all tracked directories and every action within each directory.
status [DIR]
This command will tell you your current state compared to what the current code says your state should be. For example, if you called status with no optional directory parameter, you might see something like this:
diff - db
+ db/new_function
- db/lolcats
M db/schema/deploy
ok - etc
depst will report for each tracked directory what are new changes that haven't yet been deployed (marked with a "+"), features that have been deployed in your current system state but are missing from the code (marked with a "-"), and changes to previously existing files (marked with an "M").
If you want, you can provide a specific directory to status, and it'll only report on the directory.
depst status db
clean
Let's say that for some reason you have a delta between what depst thinks your system is and what your code says it ought to be, and you really believe your code is right. You can call clean
to tell depst to just assume that what the code says is right.
preinstall
Let's say you're setting up a new system or installing the project/application, so you start by creating yourself a working directory. At some point, you'll want to deploy all the deploy actions. You'll need to init
and add
the directories/paths you need. But depst will have a cache that matches the current working directory. At this point, you need to preinstall
to remove that cache and be in a state where you can update
.
Here's an example of what you might want:
depst init
depst add path_to/stuff
depst add path_to/other_stuff
depst preinstall
depst update
deploy NAME
This tells depst to deploy a specific action. For example, if you called status
and got back results like in the status example above, you might then want to:
depst deploy db/new_function
Note that you shouldn't add "/deploy" to the end of that. Also note that a deploy
call will automatically call verify
when complete.
verify [NAME]
This will run the verify step on any given action, or if no action name is provided, all actions under directories that are tracked.
Unlike deploy and revert files, which can run the user through all sorts of user input/output, verify files must return some value that is either true or false. depst will assume that if it sees a true value, verification is confirmed. If it receives a false value, verification is assumed to have failed.
revert NAME
This tells depst to revert a specific action. For example, if you deployed db/new_function
but then you wanted to revert it, you'd:
depst revert db/new_function
redeploy NAME
This is exactly the same as deploy, except that if you've already deployed an action, "redeploy" will let you deploy the action again, whereas "deploy" shouldn't.
revdeploy NAME
This is exactly the same as conducting a revert of an action followed by a deploy of the same action.
update
This will automatically deploy or revert as appropriate to make your system match the code. This will likely be the most common command you run.
If there are actions in the code that have not been deployed, these will be deployed. If there are actions that have been deployed that are no longer in the code, they will be reverted.
If there are actions that are in the code that have been deployed, but the "deploy" file has changed, then update
will revert the previously deployed "deploy" file then deploy the new "deploy" file. (And note that the deployment will automatically call verify
.)
help
Displays a synposis of commands and their usage.
man
Displays the man page for depst.
DEPENDENCIES
Sometimes you may have deployments (or revertions) that have dependencies on other deployments (or revertions). For example, if you want to add a column to a table in a database, that table (and the database) have to exist already.
To define a dependency, place the action's name after a depst.prereq
marker, which itself likely will be after a comment. (The comment marker can be whatever the language of the deployment file is.) For example, in a SQL file that adds a column, you might have:
-- depst.prereq: db/schema
WRAPPERS
Unless a "wrapper" is used (and thus, by default), depst will assume that the action files (those 3 files under each action name) are self-contained executable files. Often if not almost always the action sub-files would be a lot simpler and contain less code duplication if they were executed through some sort of wrapper.
Given our database example, we'd likely want each of the action sub-files to be pure SQL. In that case, we'll need to write some wrapper program that depst will run that will then consume and run the SQL files as appropriate.
depst looks for wrapper files up the chain from the location of the action file. Specifically, it'll assume a file is a wrapper if the filename is "depst.wrap". If such a file is found, then that file is called, and the name of the action sub-file is passed as its only argument.
As an example, let's say I created an action set that looked like this
example/
ls/
deploy
revert
verify
Let's then also say that the example/ls/deploy
file contains:
ls
I could create a deployment file example/depst.wrap
that looked like this:
#!/bin/bash
/bin/bash "$1"
Wrappers will only ever be run from the current code. For example, if you have a revert file for some action and you checkout your working directory to a point in time prior to the revert file existing, depst maintains a copy of the original revert file so it can revert the action. However, it will always rely on whatever wrapper is in the current working directory.
SEE ALSO
AUTHOR
Gryphon Shafer <gryphon@cpan.org>.
code('Perl') || die;
LICENSE
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.