If you’ve always worked with version control systems that use file locking (where only one person can have a file checked out at at time, such as Visual Source Safe, PVCS or Clear Case), then getting used to a non-file-locking system (such as CVS or Subversion) is quite an adjustment.
It’s a change in the way you think, that starts with a change in terminology. Here’s a list of some terminology differences and best practices for use with non-file-locking systems.
- Add – Used to add new directories and files to the repository. Must be followed by a “commit” to finalize the change. Also note that a “commit” without an “add” will not include the new file or directory to the repository.
- Checkout – A one-time only action to retrieve all the code in the repository, and put it in a local working directory.
- Commit – Similar to “update” in other version control systems, this command is used to copy changes from the local directory to the repository. If adding new files, you must do “Add” before commit.
- Repository – the remote copy of your code base controlled by the CVS or Subversion server.
- Update – Similar to the term “check out” in other version control systems, this command is used to get the most recent changes from the repository, and put changes in your local working directory. This does not lock any files, nor prevent anyone from making changes to any files. If two people have made changes to a file, CVS/Subversion will attempt to merge the two files locally, and notify you if there is a conflict. This way, you have the most recent changes, and they will still be there when you commit your changes.
- Always do an “update” before beginning your work, to make sure that your local working directory has the most recent code.
- Make your code changes.
- IMPORTANT: Before “committing” your changes, do an “update” once more to make sure you get any changes since your last update,
- If someone else has been making changes to this file, and they committed their changes first, you will have to merge their changes in with yours before committing.
- If you “commit” your changes without updating first, and someone else made a change to a file you changed, you will overwrite their changes! This is not a good way to make friends on the team 🙂
- After retrieving the latest code from the repository, it is a good idea to re-run any unit tests to make sure that your new code still works along with the new code just retrieved.
- If you have created any NEW files, you must first “add” them to the repository, or they will not be included when you “commit” your code.
- Finally, “commit” your code changes, both new files and modified files.
- Update Often! Most people check email several times a day. It is not a bad idea to get the latest code changes from everyone else several times a day. This will help more quickly identify things like API changes that would result in compiler errors, etc. The bigger the team, the more important it is to keep updating to the latest version of the code.
- Commit Often! No need to wait until you’re completely done with something before checking in. There are several advantages to committing often.
- More often you commit your code, the sooner everyone else on the team will have your changes. If 2 people work on the same file, and you commit your changes first, it is the 2nd person’s responsibility to merge them together 🙂
- Committing frequently also means you will be committing smaller chunks of code, rather than giant blocks of code changes that touch many files. This reduces merge conflicts later, and reduces the chance that someone else will have to ask you about your changes if they are merging their code with yours. Smaller chunks of committed code are much easier to merge!
- In addition, it can be a good backup for yourself. If you reach a good stopping point where things work to a certain degree, commit that code. If you do this often, and something gets screwed up, it makes it very easy to revert to what you know was a working version of code and start over, without losing a lot of changes.
- Do not commit broken code! Your can commit your code even if what you are working on is still a work in progress. However, you should still follow a few rules of thumb.
- Do not commit code that does not compile!
- Do not commit code that causes unit tests to break.
- Even if your code may not fully work yet, do not commit code that causes something else that was working before to break.