FANDOM


This page is intended to give you a quick overview of getting started with the Swarm command line tool.Note that while we are in development, much of this quick start guide may not work. If you see something that needs to be done, feel free to grab the source, fix it, and post a bundle of your changes to the list... thanks.

{*} : Means that the feature is there (may not work entirely, but it's there)

{X} : Means that the feature is planned (may even have some stub work done already) but not there yet

TableOfContents

The Basics Edit

Command line syntax Edit

Swarm's CLI is designed to have a consistent syntax such that, once you've learned the syntax for one command you've learned syntax for all commands.

The syntax for the swarm cli is as follows:

swarm [OPTIONS] [COMMAND] [PARAMETERS]

where

* : [OPTIONS] are the options for the swarm command (things like "verbose", "force", etc.)
* : [COMMAND] is the swarm command (e.g., init, log, new, taxonomy, help, etc.)
* : [PARAMETERS] are the command-specific parameters

Getting Help Edit

{*} Before we begin, we should tell you how to get help inside of the swarm cli. Running swarm with no options gives you a basic usage display:

$ swarm
Swarm DITS
Swarm Distributed Issue Tracking System

basic commands, use "help" to get more details.

   help                Gives help for swarm
   copyright           Swarm copyright notice
   taxonomy            Perform a taxonomy command
   init                Initialize a swarm DITS hive in given directory
   ...

You can then request help for specific commands by issuing "swarm help command"

$ swarm help log
swarm [OPTIONS] log [ISSUE] [DIR]

Displays the log (master log or for a given issue)

  Will display the log. If [ISSUE] is empty (or 0), will
  display the master log for the DITS hive. If
  [ISSUE] is a legitimate issue, will only display the log
  pertaining to it.
  OPTIONS:
  -v|--verbose    Be verbose about actions

Swarm's ticket numbering system Edit

One thing that can throw persons new to Swarm is the way it numbers its tickets. The theory behind this ticket system is beyond the scope of this document, however here is the basic gist of it.

Because we are dealing with distributed issue tracking, we need to somehow attempt to prevent ticket number collisions. E.g., if two people working from the same base but isolated from each-other create new tickets, the numbers for those tickets need to not collide.

The method Swarm uses to avoid collisions is to assign a 40-byte hexadecimal number for the tickets. This 40-byte number is then truncated to a smaller, more human-readable, form that can be as small as 4-bytes. In the event of collision, more bytes from the original hexadecimal number are used until there is no collision.

So, when you create a new ticket, you will get a ticket number like #3a1e or #81b2. If your ticket hive is especially large, then you may get larger numbers like #19c0e4.

Thus, the one major difference between Swarm and other issue tracking systems is that the ticket numbers do not indicate any sort of ordering. I.e., whereas in another system ticket #13 is likely older than ticket #612, the same cannot be said about tickets in Swarm.

Starting Out Edit

Initializing an Issue Tracking Hive Edit

There are really two ways to prepare an issue tracking hive for use. The first is to create one from scratch, the second is to clone an existing hive.


{*} Creating a hive from scratch Edit

You can create a hive using the "swarm init" command. If called with an optional directory argument will create the hive in that directory (creating the directory if it doesn't exist):

$ swarm init some_directory

...or...

$ swarm init /path/to/some_directory

If you are already in the directory where you wish the hive to be created, you can omit the directory option

$ cd some_directory
$ swarm init

The default project name for the hive will be taken from the name of the directory.

{X} Cloning a hive Edit

A remote hive can be cloned using the "swarm clone" command. The "clone" command requires an additional argument detailing where the remote hive is. It can be a path to a hive on the local system, or one over some remote connection. Any of the following are valid:

$ swarm clone /path/to/another_directory
$ swarm clone sftp://bob@someplace.com/path/to/hive
$ swarm clone http://someplace.com/path/to/hive

NOTE: Right now, none of this works. This is a TODO.

Taxonomy Changes Edit

{*} Swarm has a number of taxonomies that are used to classify and sort the issues it tracks. By default, these taxonomies are empty and waiting for you to add to them.

To get a list of the possible taxonomies which you can edit, use "swarm taxonomy listall"

$ swarm taxonomy listall
2007 Jul 08 11:55.23 [swarm_cli.taxonomy] : Possible taxonomy terms:
        component
        version
        milestone

To then list the contents of a given taxonomy, use "swarm taxonomy list [term]"

$ swarm taxonomy list component
{'details': 'No component', 'id': '0', 'name': 'None'}
{'details': 'The SQLite backend', 'id': '1', 'name': 'SQLite'}
{'details': 'The MySQL backend', 'id': '2', 'name': 'MySQL'}
{'details': 'The web user interface', 'id': '3', 'name': 'WebUI'}

If you wish to edit a taxonomy, use "swarm taxonomy edit [term]"

$ swarm taxonomy edit component
...Brings up editor for you to edit the taxonomy contents

Creating new tickets Edit

{*} New tickets are created using the "swarm new" command.

$ swarm new
... brings up a new, blank, ticket in your editor of choice..
... The blank ticket will look something like this ...

# Create new ticket
#--------------------
# Lines begining with a '#' will be treated as a comment.
# In the header section, blank lines will be ignored
# Lines starting with '@' indicate a section divider.

@ HEADER

# timestamp: 1183933114.46
# Sun Jul  8 18:18:34 2007
# reporter: sam@rygel.home.samhart.com
component:
version:
milestone:
severity:
priority:
owner:
keywords:

@ NODE
related:
summary:

# Everything after details (including lines begining with '#' or '@') will
# be considered part of the details section
@ DETAILS

After you create the new ticket, the ticket ID will be returned:

2007 Jul 08 11:55.23 [swarm_cli.new] : Ticket #46a5 has been created.

Day to day actions Edit

Last Ticket : Keeping track of what you're doing Edit

As you are working, Swarm keeps track of the last ticket you worked on. It does this because usually ticket traffic comes in sets. E.g., you might comment on a ticket, go off and develop a patch, come back and attached the patch, maybe change ownership or some taxonomy information, perhaps add another comment, all without changing ticket numbers. Having to retype the same ticket number over and over again would be tedious when you are working on the same ticket. So Swarm keeps track of the last ticket you worked on, and assumes you will still be working on this ticket until you specify otherwise.

{*} You can tell which ticket was the last one you worked on by issuing the "swarm last" command:

$ swarm last
2007 Jul 09 16:19.58 [swarm_cli.cli_last] : The last issue was #6f12.

It should be noted that Swarm will keep track of the last issue you worked on even if you reboot your system. Thus, it's always a good idea to verify you're working on the bug you want to be with the "swarm last" command.

Ad blocker interference detected!


Wikia is a free-to-use site that makes money from advertising. We have a modified experience for viewers using ad blockers

Wikia is not accessible if you’ve made further modifications. Remove the custom ad blocker rule(s) and the page will load as expected.