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 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 redeploy 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 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.
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.
depst
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.)
init
The initialization will result in a .depst directory being created. You'll almost certainly want to add ".depst" to your .gitignore file or whatever.
.depst
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.
db
depst add db
db/schema
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 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:
make
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, 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
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.
clean
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.
add
preinstall
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
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:
status
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.
deploy
verify
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 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:
db/new_function
depst revert db/new_function
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.)
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
-- 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:
example/ls/deploy
ls
I could create a deployment file example/depst.wrap that looked like this:
example/depst.wrap
#!/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.
App::Sqitch.
Gryphon Shafer <gryphon@cpan.org>.
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.
To install App::Depst, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::Depst
CPAN shell
perl -MCPAN -e shell install App::Depst
For more information on module installation, please visit the detailed CPAN module installation guide.