How-to: Version Control for the General Users
Many different types of version control exist. This How-to is not meant to be exhaustive but to guide general users in the basic concepts and usage of version control software. It is intended for users of Subversion but many of the concepts are easily extended to include GIT and Mercurial.
What's the purpose?
Version control software manages changes to documents and other computer files. It allows for easy tracking of changes, collaboration on the same documents, and distribution of controlled versions of a document.
Consider the example
Company Alpha has 5 employees who work in the product department, some in the Canada office and some in the USA office. Alpha also collaborates with Contractor Beta and Consultant Gamma, each of which has multiple employees. Alpha has created a marvelous new product but that product is not yet fully developed. In order to get its product to market quickly, Alpha decides to start documenting its product while still in development. The documentation has been outsourced to Gamma. Additionally, Beta will perform testing on the product and its documentation. Since this is an important product, the division president wishes to always have the latest results from all collaborators readily available.
A central repository that allows users to work on a copy of the documentation and then submit or merge changes to the repository is needed. This is exactly the type of scenario that version control software was designed for.
- File data and revision history is stored in the repository.
- The most current versions of files are usually stored in the trunk.
- Files are checked out from the trunk into a local working copy.
- Files may be edited, added and deleted from the working copy.
- To ensure the working copy is the most recent version, it is important to regularly update.
- Once you have modified, added, and deleted files or folders, your local changes must be committed to the repository so that they are available to others.
- Where file data and revision history is stored, often on a server.
- Where the main line of file development occurs. Some projects also have branches and tags but those will not be covered here.
- Check out
- Action to create a local working copy of the repository, or more commonly; the trunk or specific folder within the trunk. (uses the command checkout or co)
- Working copy
- The local copy of files from a repository, at a specific time or revision. All work done to files within a repository is initially done on the working copy.
- Action to include a file or folder in the working copy as part of the repository. This is important because if you create a file but do not then use the add action, it will not become part of the repository but only remain part of the working copy. (uses the command add)
- Action to remove a file or folder in the working copy from the repository. This is important because if you do not use the delete action on your deleted file; the next time you update your working copy, the supposedly deleted file will reappear. (uses the command delete)
- Action to move or rename a file or folder. This action is equivalent to copy followed by delete. (uses the command move)
- Action to sync your working copy with the repository. If you have made local changes, it will try to merge any changes on the server with your working copy changes. (uses the command update or up)
- Action to send the changes you made to your working copy to the repository. Before you commit you should make sure that your working copy is up to date using update. (uses the command commit or ci)
- Action to undo changes you have made. This can be used to undelete a working copy file or make any working copy file the same as it was before you made any changes. (uses the command revert)
The work cycle as shown in the graphic is a typical usage of subversion. (if you are working with a source code project, different rules will apply)
- Check out the working copy from the repository.
- This only needs to be done once.
- Regularly update your working copy from the repository.
- This insures that you have the most recent versions of the files before you start making changes to them.
- Make your changes.
- If you make any mistakes, simply revert your changes.
- Regularly commit your changes to the repository.
- This insures that all of the changes you have made are available to others.
- When committing, please include a commit message. This succinctly informs others what each version update contains.
Sometimes when updating your working copy or when committing your changes, the software will prevent the action. This is done when the revision of your working copy is older than the repository revision (applied per file). This means someone else has already made changes to the same file and has already committed it to the repository. You will need to resolve the conflicts by merging the file versions. Typically this is done by hand and depending on the file type, may be an easy merge.
What You Need
- A server to host the repository
- This is beyond the content of this How-to. Instead, seek an IT professional to assist you.
- A typical public host will look very similar to a web site URL.
- Subversion client software.
- For Windows, the best client to install is TortoiseSVN which is available as a free download from TortoiseSVN
This is the subversion client software for Windows. It adds an intuitive shell extension that is integrated with Explorer. All you need to do is right click on your files or folders to view many of the available subversion commands and options. It also makes committing easy by informing you of new or deleted files and giving you the option of performing the needed action at that time.