What is the correct usage of working folders and bookmarks in Versions (Subversion Client) for local repositories?

Question

I have been using Versions, the popular Subversion client for OS X, to connect to remote Subversion repositories. These remote repositories you keep as bookmarks on the left side bar. However, when it comes to local repositories, I have to admit I am still a bit clueless. I see Versions has in addition to bookmarks, the concept of working folders. I am unsure if working folders are meant to be used separate of bookmarks or if working folders are meant to be placed inside bookmarks. What is the correct way to set up and check out a local repository?

Is the local repository folder A meant to stay separate from the folder B containing the files I want to keep under version control? Can folder B be a subfolder of A? Also, as far as how it works internally: Where are the past versions of files kept in the file system?

I created a local repository using Versions and I saw on my file system that many Subversion system files and folders were created on the local repository folder. Nowhere did I see the usual "branches", "tags" and "trunk" that I usually find on remote repositories that have already been created. Are those created by hand?

Some clarification on the barebones basics of local repositories would be appreciated. I am hoping to find out the correct workflow from set up to starting with my first check out. Thanks.

Answer 1

I have used Versions, but I prefer Cornerstone 2. It is a much more robust client.

A repository is a folder stored on a computer (local or remote.) It contains all the data regarding the version control of a set of files, stored in a data structure that most people don't need to understand.

A working folder is a folder on your local system that contains a copy of the files that are stored in the crazy data structure that is the repository.

So, if you have a local repository, that folder is stored on your hard drive. You should never need to access this from the Finder or the Terminal, or well, through any means whatsoever other that through your SVN client (Versions).

In order to work with the files stored in that local repository, use Versions to "Check Out" a working copy of the files. These files will go into a second folder somewhere on your filesystem. These files you can access directly using whatever application floats your boat. After making changes to the files, you go back to Versions and check the files into the repository. This action creates a second version of the files within the crazy data structure that is your repository.

Using Versions, you can then move back and forth through these various versions of your files. Whatever version you want to work form is then loaded into your working copy or you can check out a second working copy if you want to work with a different version of the files, while keeping your current working directory as well.

---

Here is how I arrange my SVN repositories and working directories.

First: The repositories are all stored in ~/svnroot. I have a couple of types of projects that I use SVN for, so the structure looks like this.

~/svnroot/scripts/project1
~/svnroot/scripts/project2
~/svnroot/documentation/project3
etc etc etc

Keep in mind that in each example above, the last part of the path above is the actual repository.

Second: Then I create working copies of these repositories. I keep those in the same structure in my home directory. It looks like this.

~/scripts/project1
~/scripts/project2
~/documentation/project3
etc etc etc    

Note the absence of the svnroot directory in these examples... Also, keep in mind that the last part of the path above is the directory that is under version control, otherwise referred to as the Working Copy. These are the files you can edit to your heart's content.

Then, to keep things organized, I create the scripts and documentation directories in the sidebar of Versions and put the entries for the working directories and repositories in here.

I will try to remember to provide a screenshot when I get home tonight.

Third: Now, put the files you want under version control into the Working Copy folders in the Finder. Back to Versions and check the files into the repository. Now you are all set and should be able to work.

---

Versions does not generate tags, branches, and trunks. If you want to use them in your project, create each folder in the Working Copy, and then check them into the repository. In order to create a tag or a branch, you will want to check the Versions website. Their help documentation covers that item... and it needs to be done in the repository view, not the working copy view.

http://versionsapp.com/support

Oh, and "Bookmarks" is just the term that Versions uses to keep track of your repositories and working copies in the sidebar of the main window.

Answer 2

I've been using Versions for a couple of years, but never paid attention to the idea of "bookmarks" -- even though I've used it for both local repositories and remote repositories with local working copies. So, I looked it up.

It looks like "bookmarks" is just the Versions.app list of content you've connected to, whether it's a remote svn resource for browsing, or a local copy of something you're working on remotely. There are some tips & tricks to how you set Versions to link & organize what you're working with, and you can look that up in the help (Help > Versions Help > Versions Workflow > Bookmarks).

So, the rest of the answer to your question is standard svn advice, and what @TheWellington wrote here looks right on that topic. "Working folders" are local copies of some aspect of your remote repository. Typically the code lives on a remote server, or in a "local repository" somewhere else on your disk that you don't touch directly. You make a "working folder" when you want to actually make changes. This can be tied to the "trunk", or a "branch" of the project. I suggest reading the SVN book for "best practices" tied to these -- you could start with these links:

• Version Control Basics
• Creating a Working Copy
• Using Branches

As @VxJasonxV noted, it's up to you to create the standard svn directory structure (trunk, tags, branches) by hand, and it's good advice to do so. That makes it much easier to go back in time, explore alternate paths, and know exactly what code/data is associated with a particular thing you've released into the wild.

Finally, to be clear, you should never interact with the "local repository" files on disk directly. Treat it as very cryptic black box (which it is), and use the svn client (Versions.app or command line) to access your data, examine history, etc.