FIRST STEPS ================================================================================ If you're on a Mac just launch Terminal.app. This will be in the Utilities folder of the Applications folder. If you're on a Windows machine you should download PuTTY. It's a good terminal app with support for ssh and other goodies. You can get it here http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html. If you're on a Linux box, I'm assuming you know how to load up a terminal ;) 1) ssh into itp.nyu.edu, ssh stands for Secure SHell: > ssh netid@itp.nyu.edu 2) enter in your password. 3) You should be in your home directory on itp.nyu.edu. This is just as you would expect if you had used a (s)ftp client. 4) try some commands: > ls > ls -al > pwd 'ls' lists the content of the directory. You can pass 'ls' parameters via what are called command line flags. '-a' means show invisible files. In a UNIX-like environment, invisibles files start with a '.' character. '-l' means show a longer description. This shows things like permissions, file size, ownership, and the last modified date. YOUR FIRST REPOSITORY ================================================================================ 5) type svn: > svn You should get a prompt letting you know how to get help. 6) Now we're going to make a directory where our repositories will live. You can delete this later if you want with by running 'rm -r repos' from your home directory. > mkdir repos 7) Let's create the repository. > svnadmin create repos/myFakeProjectRepo THE PROJECT DIRECTORY STRUCTURE ================================================================================ 8) now let's make our project directory structure: > mkdir myFakeProject 9) Use 'cd' to switch into this directory. 'cd' is short for Change Directory: > cd myFakeProject > pwd 'pwd' though it kinds of looks like password actually stands for Print Working Directory. If you forget where you are you can have the system let you know. 10) Let's make some more directories: > mkdir tags > mkdir trunk > mkdir branches You don't need to know what tags and branches these are for at the moment. Later you will find them useful. The important thing is to remember to set up your project structure this way. We'll only be checking out trunk, but it's a good idea to have your repository setup to scale later down the line. THE INITIAL IMPORT ================================================================================ 11) Do the initial import. The '-m' flag sets the message that will be seen in the revision history. > cd .. > svn import -m "Inital import. WOOT" myFakeProject \ file:///home/netid/repos/myFakeProjectRepo the first line moves you up one directory. In UNIX land . stands for the current directory and .. stands for the parent directory. 12) Switch back to your home directory: > cd ~ '~' is short your home directory. 13) Remove the myFakeProject directory: > rm -r myFakeProject What?! I know what you're thinking, it's OK. You project is much safe now in the repository than it ever will be as a normal project directory. THE WORKING COPY ================================================================================ 14) It's time to check out a working copy of your project: > cd ~ > svn co file:///home/netid/repos/myFakeProjectRepo/trunk myFakeProject You should see some output while your brand new working copy gets checked out. You can edit this working copy and svn will track the changes that differ from the version existing in the repository. 15) Check the status of your working copy: > cd myFakeProject > svn status Since there aren't any local changes yet you will just see the revision number, you won't see anything. > svn log This will show you all the revisions of this project. MODIFYING YOUR WORKING COPY ================================================================================ 16) Let's add a file to the repo with 'nano'. 'nano' is a command line based text editor. It's fairly simple and will save in those situations where you really need to edit a file on the server. > cd myFakeProject > nano first.js 17) Most of the commands you can use are at the bottom of the screen, ^ stands for the control key. Type the following into the file. function init() { alert("Hello, world!"); } When you're done type CONTROL-O. You may need to specify the filename, press ENTER. Quit nano with CONTROL-X. 18) Check the repo status: > svn status Subversion should show you the new file with a question mark. This is because Subversion doesn't know about this file yet. We need to add it to our working copy. > svn add first.js You should get some feedback that this file has been added 19) Let's commit it, and run svn status again: > svn commit -m "Added first.js" > svn st st is shorthand for status. You shouldn't see anything now since all your changes have been committed. > svn log Weird it doesn't show your latest commit. This is because your working copy isn't up-to-date with the latest information in the repository. > svn update > svn log You should now see both commits. 20) Let's add line to the file. > nano first.js Make the file looking like the following: function init() { alert("Hello, world!"); alert("Goodbye, world!"); } Save and exit as before with CONTROL-O and CONTROL-X 21) Let's check the status again > svn st Subversion will list the first.js file with a M. This means that the file has local changes that different from the status of the project in the repository. Let's commit these chagnes. Let's see what's different. > svn diff first.js This simply checks your working copy of first.js with the one in the repository. You can see that you've added one new line of code. > svn commit -m "Added another line to init.js" > svn update > svn log CHECKING OUT A WORKING COPY FROM A REMOTE REPOSITORY ================================================================================ Having to edit on the server is not always ideal, especially if the internet connection is spotty as it usually is over wifi. Often you want to keep a local copy on your laptop and commit changes to the central repository so that other people can pick up those changes. For this to work you need to have a local copy of subversion installed. This is beyond the scope of this particular tutorial and there's plenty of resources on the web. If you're on a Windows machine you'll have to do some work. On a Mac, Subversion is already installed. On Linux, once again, I imagine that you already know how to get it. 1) You can use the following command to check out a repo from itp.nyu.edu onto your local machine. Launch a terminal application locally. Or if you're already in a termainl and still logged in you can either > exit which will log you out of your ssh session. You can also just open up a new terminal window. > cd ~ This will switch you to your home directory on your computer. > svn co \ svn+ssh://netid@itp.nyu.edu/home/netid/repos/myFakeProjectRepo/trunk \ myFakeProject You will be prompted for your password. If all goes well you'll have a local copy on your machine. If you don't want to prompted for your password each time you run an svn command on your local copy you'll need to read up on ssh-keygen and ssh-agent. You can find a tutorial about this here http://www.duke.edu/~herb/security/acpub-ssh-faq.html#ssh-add On a Mac with Leopard installed you can add your private keys to your keychain so you don't have type in your password each time. Also any apps such as Transmit, Coda, Fetch, or other app that might need access to your private key can grab it automatically via the system keychain. WRAPUP ================================================================================ That's the basics of Subversion. When the other person commits changes they should let everyone working on the project know so that everyone can keep their project up-to-date and conflicts don't occur. While it's possible for people to work on the same file at the same time, Subversion is very bad at merging, so it's generally a good idea to avoid this. SUBVERSION CLIENTS ================================================================================ Learning how to use Subversion from the commandline is critical. Many basic features are not available in the popular GUI clients. However for day-to-day work a GUI client will usually suffice. Mac Clients Free ------------------------------ svnX Mac Clients $$$ ------------------------------ Cornerstone Versions Textmate SVN Bundle Windows Clients Free ------------------------------ TortoiseSVN Linux Clients Free ------------------------------ RapidSVN On a Mac I recommend svnX until you get the hang of things. If you are willing to spend a little money, Cornerstone is very good. On a PC Tortoise SVN integrates very well with the Windows environment.