Getting Started Tutorial
Introduction:
This tutorial is a simple guide to getting started with SD, so that you can use it to track issue on a project hosted on GitHub. By the end of this tutorial, you'll know the basic functionality of SD and be ready to explore the more sophisticated features. You will be able to clone a GitHub issue database, update, create and close issues offline and sync your changes to GitHub when online again.
1. Install SD.
SD is installed using the "one tweet install", which is by simply typing the following into your command line:
curl fsck.com/sd|perl
(you will need curl and Perl installed on your machine for this to work)
This will download and install SD onto your system. This involves downloading all the Perl modules that are required for SD along with SD itself. Post installation, SD will be working. However, you may need to add some environment settings to your system to make SD work more smoothly.
You may also need to add the following lines to your .bash_profile file (at least on OSX).
export PATH=/Users/yourUsername/sd/bin:$PATH
export SD_REPO=/Users/yourUsername/Documents/yourRepo
2. Clone your GitHub issues.
The next step is to create a clone of your GitHub issues. To do this you may wish to use the SD Git integration, so navigate to your local repository for the GitHub project. From there we will run the SD command to clone the issues from GItHub.com:
git sd clone --from github:/ so for example to clone the SD issues you would use git sd clone --from github:bestpractical/sd
This will initialise and pull the issues from GitHub, creating your local copy of all the issues. Now you can browse, update, open and close issues offline.
3. Using SD.
Often the easiest way to get started with SD for new users is to use the web interface, which runs locally on your computer without need for the internet. To start the web interface for your GitHub project (cloned above) type the following in at the command line:
git sd browser
This will start the micro webserver and open your default browser to the web interface. You will be able to click the menu items and browse the issues and update them. You can create new issues, etc.
In step 5 we will discuss using the command line to update, create and close issues, but for now make some changes in the web interface before moving on to step 4. Once you have made some changes you will probably close the web gui by pressing CTRL+C in the command line window.
4. Sync with remote data.
Syncing data with your remote data (in our case GitHub) you either push or pull data to/from the remote location. This is done via the command line, below is the command to push your changes to the GitHub data we are using in this example:
git sd push --to github:/ (again replacing the <USERNAME and with details of your project)
Depending on the situation, SD may ask you some questions about how you would like to resolve conflicts, choos the defaults for now if that happens. Conflict resolution will be covered in another tutorial.
At this stage you may want to visit the GitHub website and confirm your changes are visible.
Next make a change on the website (ceate a test issue perhaps?) and we will pull that change into your local data with the following command:
git sd pull --from github:/ (again replacing the <USERNAME and with details of your project)
To check if the new test issue is synced to your system type the following command to get a list of issue tickets on your local system:
git sd ticket list
You should now see the new issue. It's only a test so lets update it, but this time from the command line.
5. Updating issues from the command line.