depst - Deployment State Manager
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 # check status of tracked directories depst diff [NAME] # display a diff of any modified actions 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
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.
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.
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.
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.
This removes a directory from the depst tracking list.
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`
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.
This command will tell you your current state compared to what the current code says your state should be. For example, 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").
This will display a diff delta of the differences of any modified action files. You can specify an optional name parameter that refers to a tracking directory, action name, or specific sub-action.
depst diff depst diff db/schema depst diff db/schema/deploy
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.
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
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
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
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.
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.
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
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.
This is exactly the same as conducting a revert of an action followed by a deploy of the same action.
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
Displays a synposis of commands and their usage.
Displays the man page for depst.
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
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:
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.
Gryphon Shafer <email@example.com>.
code('Perl') || die;
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.