Getting started with SD
SD is a peer to peer ticket tracking system built on the Prophet distributed database. SD is designed to make it easy to work with tickets and to share ticket databases with your collaborators.
You can watch this Youtube video of SD in action: http://youtu.be/w2e-TL_Vtwc
To get started with SD, you need a ticket database. To get a ticket database, you have two options: You can clone an existing database or start a new one.
SD will store its local database replica in the path specified by the SD_REPO environment variable. Generally, you will want to use a shell script or alias wrapper to set this variable if you have more than one SD replica. Two scripts distributed with SD will set SD_REPO from the VCS of the project directory you're currently in: git-sd and darcs-sd. If you write a wrapper for another VCS, please contribute it back!
To clone a ticket database:
sd clone --from http://example.com/path/to/sd
To start a new ticket database:
sd init
Or, using the git-sd script within a project checkout:
git sd init
To configure your project's name, milestones and components:
sd settings edit
To create a ticket, run:
sd ticket create
To list all tickets in your database:
sd ticket list
To publish your database:
sd publish joeuser@myhost.example.com:public\_html/mydb
To learn a bit more about what you can do with SD:
sd help
Searching for and displaying tickets
sd ticket search
List all tickets with a status that does not match 'closed'. Note that 'list' is an alias for 'search'.
sd ticket search --regex abc
List all tickets with content (in any property) matching 'abc'. Regular expressions are Perl regexes.
sd ticket search -- status!=closed summary =~ http
List all tickets with a status property that does not match closed and a summary matching 'http'.
sd ticket search --group owner sd ticket search -g owner List all tickets with a status property that does not match 'closed', grouped by owner. sd ticket search --sort due sd ticket search -s due List all tickets with a status property that does not match 'closed', sorted by due date. sd ticket basics 1234
Show basic information (metadata only) for the ticket with local id 1234.
sd ticket show 1234
Show basic information and history and list attachments for the ticket with local id 1234.
sd ticket details 1234
Show basic information, comments, and history, and list attachments for the ticket with local id 1234.
sd ticket show 1234 --all-props sd ticket show 1234 -a
Show all properties of the given ticket, even if they aren't in the database setting common\_ticket\_props (or local configuration variable 'ticket.common\_props' if it exists).
sd ticket show 1234 --skip-history sd ticket show 1234 -s
Show only metadata and a list of attachments for the ticket 1234 (but not history).
sd ticket show 1234 --with-history sd ticket show 1234 -h
Override the ticket.no-implicit-history-display config option if it is set for this replica. (See 'sd help config' for more info.)
sd ticket history 1234
Show history for the ticket with local id 1234.
sd ticket delete 1234
Delete ticket with local id 1234.
Creating and Updating tickets
sd ticket create
Invokes a text editor with a ticket creation template. Note that 'new' is an alias for 'create'.
sd ticket create --verbose sd ticket create -v
Invokes a text editor with a ticket creation template and also shows descriptions and valid values for properties.
sd ticket create -- summary="This is a summary" status=open
Create a new ticket non-interactively.
sd ticket update 123 -- status=closed
Sets the status of the ticket with local id 123 to closed. Note that 'edit' is an alias for 'update'.
sd ticket update 123
Interactively update the ticket with local id 123 in a text editor.
sd ticket update 123 --verbose sd ticket update 123 -v
Interactively update the ticket with local id 123 in a text editor and show descriptions and valid values for props.
sd ticket update 123 --all-props sd ticket update 123 -a
Interactively update the ticket with local id 123 in a text editor, presenting all the props of the record for editing instead of just those specified by the database setting 'common\_ticket\_props' (or local configuration variable 'common\_ticket\_props' if it exists).
sd ticket update fad5849a-67f1-11dd-bde1-5b33d3ff2799 -- status=closed
Sets the status of the ticket with uuid fad5849a-67f1-11dd-bde1-5b33d3ff2799 to closed.
sd ticket take 123
Sets the owner of ticket 123 to you (your email address is taken from either the 'email\_address' local config variable or the EMAIL environmental variable). An alias of 'take' is 'claim'.
sd ticket give 123 nobody@example.com
Sets the owner of ticket 123 to nobody@example.com. An alias of 'give' is 'assign'.
sd ticket resolve 123 sd ticket close 123
Sets the status of the ticket with local id 123 to closed.
sd ticket resolve 123 --edit sd ticket resolve 123 -e
Sets the status of the ticket with local id 123 to closed, allowing you to edit any properties in an editor and optionally add a comment in the process.
Working with ticket comments
sd ticket comment 456
Add a comment to the ticket with id 456, popping up a text editor.
sd ticket comment 456 --file=myfile sd ticket comment 456 -f myfile
Add a comment to the ticket with id 456, using the content of 'myfile'.
sd ticket comment 456 --content="The text of the comment." sd ticket comment 456 -m "The text of the comment."
Add a comment to the ticket with id 456, specifying its content on the commandline.
sd ticket comment list
List all ticket comments.
sd ticket comment show 4
Show ticket comment 4 and all metadata.
sd ticket comments 9
Show all comments belonging to the ticket with id 9.
Working with ticket attachments
sd ticket attachment create 456 --file bugfix.patch sd ticket attachment create 456 -f bugfix.patch
Create a new attachment on this ticket from the file 'bugfix.patch'.
sd ticket attachment list 456
Show all attachemnts on ticket 456.
sd ticket attachment show 567
Show the properties of attachment 567 (including the content).
sd ticket attachment content 567
Send the content of attachment 567 to STDOUT.
sd ticket attachment content 567 > to\_apply.patch
Save the contents of attachment 567 to a file so the patch can be applied.
Sharing ticket databases
sd clone --from http://example.com/path/to/sd
Create a new copy (replica) of a published SD replica from an http, ftp or file URL.
sd pull --from http://example.com/path/to/sd
Integrate changes from a published SD replica over http, ftp or file URL.
sd pull --all (or -a)
Integrate changes from all replicas this replica has pulled from before.
sd pull --local (or -l)
Integrate changes from all replicas currently announcing themselves on the local network using Bonjour.
sd publish --to jesse@server:path/to/destination
Publish a copy of this replica to a remote server using rsync.
sd publish --html --replica --to jesse@server:path/to/destination
Publish a copy of this replica, including a static html representation, to a remote server using rsync.
sd server --port 9876
Start an sd replica server on port 9876. This command will make your replica browsable and pullable by anyone with remote access to your computer. Changes will only be accepted from the local machine.
To clone from this replica use:
sd clone --from http://hostname\_for\_server:9876/replica/
Adjust port to the server, and notice the /replica/ path.
sd browser --port 9876
Do the same as the server command, but also open up the server's front page in your browser.
SD can sync to external systems as well as itself. Currently, there are foreign replica types for:
- RT (http://bestpractical.com/rt)
- Hiveminder (http://hiveminder.com/)
- Trac (http://trac.edgewall.com)
- Google Code (http://code.google.com)
- GitHub (http://github.com)
Read-only support is available for:
Redmine (http://redmine.org)
If you're interested in building a replica type for your bug tracker, you should get in touch with SD's developers (see http://syncwith.us/contact).
The RT server is specified as as rt:serveraddress|Queue|Query
sd clone --from "rt:http://rt3.fsck.com|rt3|Owner='jesse'"
Create a local replica and pull data from a foreign replica.
sd push --to "rt:http://rt3.fsck.com|rt3|Owner='jesse'"
Push changes to the given foreign replica. Foreign replica schemas will vary based on the replica type.
sd pull --from "rt:http://rt3.fsck.com|rt3|Owner='jesse'"
Pull changes from a foreign replica to be merged into the local replica.
Cloning from Google Code sd clone --from gcode:k9mail Cloning from Trac sd clone --from trac:https://trac.parrot.org/parrot Cloning from GitHub sd clone --from github:miyagawa/remedie
SD uses LWP for HTTP access, so it supports any form of authentication LWP can use. For instance, you can push and pull from a remote trac that uses x509 client certificates by setting the HTTPS_CERT_FILE and HTTPS_KEY_FILE environment variables, and specifying an empty password when SD prompts you. For more information, see the documentation for LWP and Crypt::SSLeay.
SD also supports naming replicas, so you can push, pull, and publish to short, human-friendly names instead of URLs. When a replica is initialized, cloned, or published, a [replica "name"] section is created in the replica-specific configuration file (replica_root/config). Its name is, by default, the URL you passed to the command. You can change this to a more memorable name with:
sd config edit
You can then use sync commands like this:
sd pull --from name sd push --to name sd publish --to name
For pull and push, the given name is substituted with the value of the replica.name.url config variable. For publish, replica.name.publish-url is used. If different urls are needed for push and pull for a given replica, you can override replica.name.url with replica.name.push-url and/or replica.name.pull-url.
Viewing Database History
You can view a history of all changes to the database using the 'log' command. It can be run in the following ways:
sd log
Shows the last 20 changes.
sd log --all sd log -a
Shows the entire history from start to end.
sd log <since>..<until>
Shows the range of history starting at and ending at . Ranges can be specified using either sequence numbers or an offset from the most recent change, designated by LATEST~offset.
Examples:
sd log 0..5
Shows changes 0 through 5.
sd log LATEST
Shows the most recent change.
sd log LATEST~4
Shows changes from 4 before the most recent change up to the most recent change.
sd log 2..LATEST~5
Shows the second change up through 5 before the latest.
sd log LATEST~10..LATEST~5
Shows changes from 10 before the latest to 5 before the latest.
Environment variables
The following environmental variables can be set to affect SD's configuration. Example syntax is for bash-like shells.
export SD\_REPO=/path/to/sd/replica
Specify where the ticket database SD is using should reside.
export PROPHET\_EMAIL=jesse@example.com
Use 'jesse@example.com' as the creator of changesets. Prophet will use EMAIL if PROPHET\_EMAIL isn't defined.
export SD\_CONFIG=/path/to/sd/config/file
Specify where the configuration file SD is using should reside. If this variable is specified, no other config file will be loaded.
export PROPHET\_HISTFILE=~/.sd-history
Specify where the interactive shell should store its history.
export PROPHET\_HISTLENGTH=100
Specify how much history the interactive shell should store.
export PROPHET\_DEVEL=1
Turn on various development mode checks, warnings and autoreloading of modules.
export PROPHET\_REPLICA\_TYPE=prophet
Use the prophet native replica type. Other backend replica types are: sqlite.
For information on SD database configuration files, see 'sd help config'.
Configuration Options
SD supports a layered configuration system with three configuration files: a global file (/etc/sdrc), a user-wide configuration file ($HOME/.sdrc) and a per-replica configuration file (/path/to/replica/config). Configuration variables in more local configuration files override those in more global ones.
You can use the 'sd config' command to view what configuration files SD has loaded and all loaded configuration variables, as they apply to the current replica.
'sd config' can also be used to set configuration variables.
Examples:
sd config user.email-address user@example.com sd config --delete user.email-address sd config user.email-address
Print the current value of this configuration variable.
sd config alias.'this.alias.contains.dots' 'so it must be quoted' sd config edit sd config edit --user sd config edit --global
Edit the specified config file in an editor.
The configuration file format is similar to that of the VCS 'Git'. See http://www.kernel.org/pub/software/scm/git/docs/git-config.html for specifics. The biggest thing you need to know is that the config file contains key/value variables, contained in sections and subsections.
In the help documents, we'll refer to variables in the manner: "section-name.subsection-name.variable-name". In a configuration file, this would look like:
[section-name "subsection-name"] variable-name = value
Here's an example of an actual configuration file, aimed at being a user-wide config file that affects all bug databases:
[user] email-address = me@example.com [ticket] summary-format = %5.5s,$luid | %8.8s,status | %7.7s,component |%12.12s,owner| %-44.44s,summary default-group = milestone [alias] mine = ticket list -- owner=~me status!~closed|rejected
Currently, the following configuration variables are available (sorted by configuration file section):
ticket.summary-format = %4s },$luid | %-11.11s,status | %-60.60s,summary
Specifies how to format ticket summaries (when listing tickets, e.g.). (See also: 'sd help ticket.summary-format'.)
ticket.common-props = id,summary,status,owner,created,original\_replica
A comma-separated list of ticket properties that are most-often used. These properties will be shown by default in the 'ticket show' command and presented for editing when interactively creating or updating tickets. (Overrides the database-wide setting of the same name.)
ticket.default-sort = status
Bug property to determine order of display when displaying lists of tickets. (Can be any property; will be compared lexically.)
ticket.<prop>.sort-undef-last = true
When sorting on , setting this will make tickets where the property is undefined sort *after* any records where the property *is* defined. (The default is the opposite.) Useful for e.g. due dates.
ticket.default-group = milestone
Bug property to group tickets by when displaying lists of tickets. (Can be any property.)
ticket.show.disable-history = 1
Don't display ticket history when running 'sd ticket show'. Can be overridden by passing the '--with-history' arg to the command.
user.email-address = foo@bar.com
Specifies an email address to use as the default for tickets' reporter field. (Overrides the EMAIL environmental variable if that is also set.)
server.default-port = 8080
Specifies a default port to use for the 'server' and 'browser' commands. Can still be overridden by passing '--port' to these commands.
For information on environmental variables that can affect SD, see 'sd help environment'.
Creating and Updating tickets
sd ticket create
Invokes a text editor with a ticket creation template. Note that 'new' is an alias for 'create'.
sd ticket create --verbose sd ticket create -v
Invokes a text editor with a ticket creation template and also shows descriptions and valid values for properties.
sd ticket create -- summary="This is a summary" status=open
Create a new ticket non-interactively.
sd ticket update 123 -- status=closed
Sets the status of the ticket with local id 123 to closed. Note that 'edit' is an alias for 'update'.
sd ticket update 123
Interactively update the ticket with local id 123 in a text editor.
sd ticket update 123 --verbose sd ticket update 123 -v
Interactively update the ticket with local id 123 in a text editor and show descriptions and valid values for props.
sd ticket update 123 --all-props sd ticket update 123 -a
Interactively update the ticket with local id 123 in a text editor, presenting all the props of the record for editing instead of just those specified by the database setting 'common\_ticket\_props' (or local configuration variable 'common\_ticket\_props' if it exists).
sd ticket update fad5849a-67f1-11dd-bde1-5b33d3ff2799 -- status=closed
Sets the status of the ticket with uuid fad5849a-67f1-11dd-bde1-5b33d3ff2799 to closed.
sd ticket take 123
Sets the owner of ticket 123 to you (your email address is taken from either the 'email\_address' local config variable or the EMAIL environmental variable). An alias of 'take' is 'claim'.
sd ticket give 123 nobody@example.com
Sets the owner of ticket 123 to nobody@example.com. An alias of 'give' is 'assign'.
sd ticket resolve 123 sd ticket close 123
Sets the status of the ticket with local id 123 to closed.
sd ticket resolve 123 --edit sd ticket resolve 123 -e
Sets the status of the ticket with local id 123 to closed, allowing you to edit any properties in an editor and optionally add a comment in the process.
Command Aliases
You can create custom command aliases in the aliases section of your local configuration files. The format is as follows:
[alias] command to type = command to translate it to
As an example, you could create an alias to show all tickets assigned to you with the alias 'mine':
mine = ticket list -- owner=you@domain.com status !~closed|rejected
By default, any additional arguments to aliases are appended to the replacement text, so you can write something like
alias tl = ticket list
and
tl -- owner=you@domain.com
will work like you expect. In order to do more complicated things with arguemnts, you can use the number of an argument, prefixed by a '$', like this:
ts = ticket show $1 -s
SD also provides a command for managing aliases: 'sd aliases'. If given no arguments, the aliases command will print the active aliases for the current repository (including all non-overridden user-wide and global aliases, if any). 'sd aliases edit' will present you with an editor window in which aliases can be modified. Aliases will be saved to your local configuration file when editing is done.
Examples (in all examples, 'alias' can be used anywhere 'aliases' appears and vice-versa):
sd aliases sd aliases show
Show currently active aliases.
sd aliases edit
Edit aliases in an editor window.
sd alias "command to type" "command to translate to"
Set the given alias (or change it if it already exists).
sd aliases delete "command to type"
Delete the given alias.
The --user and --global arguments can be used in conjunction with the set (and edit) commands to change what configuration file to use. By default, the repository-specific configuration file is used.
For more information on local configuration files, see 'sd help config'.
Database Settings
The 'settings' command allows you to modify configuration variables that propagate with the current database, known as settings.
If given no arguments, the settings command will print the current settings.
The following arguments are supported:
show
Don't present an editor window, just print the current settings to STDOUT.
edit
Present an editor window containing all the current settings for interactive editing.
set -- common\_ticket\_props '["id", "summary", "original\_replica"]'
Update the setting common\_ticket\_props to the given value. Any setting, including multiple settings, may be set this way.
Setting values must be valid JSON.
Settings are not the same as local configuration variables. For more information on local configuration, see 'sd help config'.