Also be sure and check out this step-by-step guide to Subversion for use with the FIRST 971 team. Michael
Vocabulary
- Repository
- -The files and folders on the server that contain the all the revisions that have ever been checked in.
- -You should never have to create one.
- -Every repository has a unique URL that you use to check it out.
- Working Copy
- -The files and folders on your computer that you work on.
- -You can have multiple ones in different locations on your computer.
- -There will be a folder named .svn in the root and each subfolder of a working copy. You should never touch this directory.
- -Each one has a URL which must be that of the repository or any folders in it.
- Check In or Commit
- -Using your client to send changes you have made in your working copy to the repository.
- -You should write a good commit message to go along with it.
- -Each commit creates a revision which is stored in the repository permanently.
- -You should also write a good message to go along with it.
- Update
- -Using your client to download any revisions that have been checked in to the repository since you last updated or checked out a working copy.
- -You can also update to a specific revision number to look at an older version.
- Revision
- -The state of all the files and folders in a repository at a certain point in time.
- -Exactly one uniquely numbered revision is created for each successful commit.
- Check Out
- -Using your client to create a new working copy on your computer.
- -You should not perform a check out into an existing working copy.
- Conflict
- -What happens when one person checks in modifications or deletions and another person attempts to check in changes to the same file(s) before updating their working copy.
- -This is why you should always update before beginning to work on anything.
- -With text files, your client will sometimes merge changes you have made with the ones coming from the repository. This is indicated with a "G" in the left-hand column where normally only "A", "U", and "D". If you see this with a binary file such as a solidworks file, then you should revert the file.
- Client
- -The software program that runs on your computer and communicates with the repository.
- -While it usually interacts with a working copy too, most clients can list the files and folders at a given URL also.
- URL
- -In the context of SVN, a URL identifies a single file or folder in a repository.
- -Each repository also has a URL, which represents the root folder.
- -URLs in SVN always start with
svn:, http:, or https:. It matters a lot which one of these it is. You can almost never check in to a http: URL because they are not secure. If you have a http: or https: URL, you can put it into the address bar of a web browser to view a file or folder without having to check anything out.
Checking In Well
When you check in, there are several important things you should always do.
- 1. Think about exactly why you are checking in. If you have just finished 1 file and are planning to work on more, you should not check in. Instead, if there is no reason to check in immediately, finish your work for the day and then check in.
- 2. Think about which files you have changed. After closing all files in any editors (like Solidworks), look at all of the files that have been changed. You should revert any files that you did not change (in TortoiseSVN, you can right click files in the commit dialog and click "Revert..."). This is important because it helps prevent conflicts and save server space because each revision is permanent.
- 3. Write a good commit message. A commit message should always describe what you have changed. When writing a commit message, you should always keep in mind it's purpose. The purpose of a commit message is to make it easier to find out when changes were made to files and folders. When someone is viewing your commit message, it will always be along with the date and time of your commit, the names of all of the files and folders that were changed and how they were changed, the SVN username you are using, and all of the other commit messages in order. This means that you should NOT put the full names and paths of all the files that you edited into the commit message!! Instead, you should put a description of what the goal of your changes was. Also, saying "here are my changes" is not very helpful, because there is no other reason for a commit message. For example, instead of something like
"today (2/23/2011) i edited CAD/roller_claw_number_2.SLDPRT, CAD/roller_claw_assembly.SLDASM, and CAD/roller_wheels.SLDPRT and created CAD/roller_claw_reinforcement_piece.SLDPRT"
you should write something like
"fixed some dimensions on the claw and added a reinforcement piece to it"
because anybody looking at your commit message will be able to see that you modified those 3 files and created that one. However, what they will not be able to tell without a lot of work is what your changes did (fixed the size and made it stronger).
