Revision control system tutorial
Revision control system (RCS) or Version control system (VCS) or Source code management (SCM) stands for systems that allow software developers to manage application source code, including its various revisions. It also allows users to download various versions.
- Learning goals
- Be able to download software from CVS and SVN revision control systems, provided that you will find a correct CVS or SVN "string" on some download page
- Be able to use command line tools
- Moving on
- Follow up the links below.
- Level and target population
- low (there be some mistakes too), but you it should get you going...
- To do
- Add an explanation on how to use 1-2 GUI tools
- Purpose of source control
- Popular open source systems
- CVS. There exist several variants of this software. It was once upon a time the most popular system and therefore still being used.
- Subversion. Subversion was designed as a CVS replacement and is todays (2008) most popular system in the open source community.
2 Installing a client
In order to use a RCS, you need to install some software on your computer. There exist several sorts of programs:
- Command line tools (I find them most practical for just checking out something, since I usually download files from a repository directly to a server machine).
- Extensions for IDEs and text editors.
- Stand-alone GUI programs.
2.1 CVS command-line client
The program is called cvs. If it is not already on your system, install it. In Ubuntu Linux (and other Debian-based systems) type:
sudo apt-get install cvs
2.2 Subversion command-line client
The program is called svn. To install it under Ubuntu, type:
sudo apt-get install subversion
2.3 GIT command-line client
Under Ubuntu, type:
sudo apt-get install git-core
3 How to get software from CVS
3.1 Checking out software with the command-line client
The command line client is called cvs and you will use the checkout (aka co) command.
- Most simple version
cvs checkout CVS_REPOSITORY_STRING cvs co CVS_REPOSITORY_STRING
- Using a repository - the methods
There exist several ways to get files from a repository on the Internet. The general syntax for a CVS_REPOSITORY_STRING is:
cvs checkout :METHOD:USER@HOSTNAME:PATH_TO_REPOSITORY
The following means to use rsh, ssh etc. to get the file through user "anonymous"
The following will use a password authentication server through user "anonymous"
In other words, this cvs repository string contains several informations:
- host: e.g. test.org
- repository path: e.g."/software/thething"
- user: e.g. "anonymous"
- connection type: e.g. pserver
- port: default (2401)
- Checking out a file from a repository
Here is an example from the Mozilla organization
First you will have to login:
cvs -d :pserver:firstname.lastname@example.org:/www login
Hit return when it will ask for a password.
Then you can check out something, e.g.
cvs -d :pserver:email@example.com:/www -z3 co mozilla-org/html/quality/networking
The "-z3" just means that files should be compressed/decompressed in the transfer, i.g. you gain some download speed.
Instead of using the -d :pserver:firstname.lastname@example.org:/www argument you also may set the $CVSROOT variable. (Read Environment variable for a how-to).
4 How to get software from Subversion (SVN)
4.1 Subversion protocols
Subversion can be accessed trough several protocols:
The downloading instructions should tell you which one to use.
4.2 Checking out software with the command line tool
Open a terminal window. Then use the svn command.
In the most simple case, you will simply have to replace "URL" by the URL that you will find in the downloads instructions.
svn checkout URL - or - svn co URL
If you already have a version and want to update the same branch of development, type:
svn update - or - svn up
However, sometimes you will have to provide extra information, e.g. for Moodle, type:
cvs update -dP
or to get a new specific version
cvs update -dP The_Moodle_Version_you_need
- Example - Mediawiki software
To get the mediawiki software, you need a URL like this (as is it won't work).
svn checkout http://svn.wikimedia.org/svnroot/mediawiki/folders_to_download sub_folder_name
E.g. to download version 13 (oct 2008), you will have to type:
To download the development version:
Of course, to install a new MediaWiki version, you usually would just download an *.gz archive. But extensions (and there lots of them) are often available through the MediaWiki subversion archive. It's simpler to use subversion than saving each file individually from the web interface.
To view extension code through the web:
To check it out, type in your terminal:
The result will be 4 files in the NewsChannel directory (faster isn't it ?)
- Putting files in a different directory
If you don't want to cd to a given directory, you also can add a path:
svn checkout http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/NewsChannel/ /src/NewsChannel
4.3 Information with the command line tool
The info command will provide you with some information, e.g. try:
svn info http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/ svn info http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/NewsChannel svn info http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/NewsChannel --recursive
4.4 Getting help with the command line tool
Besides reading various tutorials, you also may type:
or for a specific topic, e.g.
svn --help checkout svn --help co
Some repositories don't want anonymous users to check out files. In this case, you need a user name and maybe a password.
svn checkout URL --username USER --password PASS
5 How to get/push software from/to GIT
GIT is the newest kid on the block. Text below should not be trusted. I am new to Git and just wrote down a few barebones I needed - Daniel K. Schneider 18:50, 10 December 2012 (CET)
“Git is a distributed revision control system with an emphasis on speed. Git was initially designed and developed by Linus Torvalds for Linux kernel development. Every Git working directory is a full-fledged repository with complete history and full revision tracking capabilities, not dependent on network access or a central server.”(Wikipedia, retrieved 14:33, 30 August 2010 (UTC))
“Repositories can be published via HTTP, FTP, rsync, or a Git protocol over either a plain socket or ssh. Git also has a CVS server emulation, which enables the use of existing CVS clients and IDE plugins to access Git repositories. Subversion and svk repositories can be used directly with git-svn.”(Wikipedia, retrieved 14:33, 30 August 2010 (UTC))
5.1 First download of GIT repository
Typical download command
git clone git://URL/branch
Examples from non Git-hub servers (Mwlib software from PediaPress and Mediawiki)
git clone git://code.pediapress.com/mwlib git clone https://gerrit.wikimedia.org/r/p/mediawiki/core.git
5.2 Updating with GIT
cd <git directory> git remote -v
Get all new files from the repository and merge with the local directory.
cd <git directory> git pull
Get, but don't merge
cd <git directory> git fetch
Track another version (before a pull for example)
cd <git directory> # List the remote branches git branch -r # List the local branches git branch -l git checkout THE_NEW_BRANCH
Track/switch to another version where a name is specified for the local branch
git checkout THE_NEW_BRANCH -b NEW_LOCAL_BRANCH
git checkout origin/REL1_22 -b REL1_22
Same principle, but arguments are given in different order
git checkout -b REL1_21 origin/REL1_21
Forcing a bit. Example: Track another version and force a bit, i.e. reset if something (what?) is wrong
git checkout origin/REL1_22 -B REL1_22
git checkout origin/wmf/1.24wmf22 -b 1.24wmf22
.... Branch 1.24wmf22 set up to track remote branch wmf/1.24wmf22 from origin. Switched to a new branch '1.24wmf22'
- If you get a message like error: you need to resolve your current index first
To get more information, type
Resetting local files, i.e. overwrite local files (does not always work)
git reset --hard HEAD git pull
Depending on the bad state, fixing problems is not easy. E.g. with a message like "Please, commit your changes or stash them before you can switch branches. Aborting " try
sudo git checkout -- .
git reset --merge
- but before that make sure that the name of your branch matches the name on remote, e.g. for alpha code try
git checkout origin/master -B master
The following does a radical reset and may destroy important files, e.g. the configuration file
// simulate git clean -xfnd // do it git clean -xfd
The next is less radical and only will clean a directory and its subdirectories
git clean -f directory -d
Make it interactif (strongly recommended): Add the -i flag, e.g.
git clean -i
Tags are not like branches, they can't move and will identify some sort of snapshot (if I understood right)
git tag -l | sort -V
To use a specific tag:
git checkout <tag name>
See your configuration
git config -l
- Tells which files are tracked/untracked
- Which files are tracked an not committed
Log file of operations
Log file showing changes (diffs between files)
git log -p
Show all your remote servers
git remote -v
1) Tell who you are
git config --global user.name "xxxx" git config --global user.email "xxx@..."
2) All connections must be made as the user "git".
ssh -vT email@example.com
3) You must have a public/private key pair set,either dsa or rsa
Got to your .ssh directory and create those guys:
pushd ~/.ssh ssh-keygen -t rsa -C "your_mail@your_domain"
This will create two files:
4) Now tell githut about it using the web interface
Paste the id_rsa.pub content to your clipboard
xclip -sel clip < ~/.ssh/id_rsa.pub
Add the key to
- Click "Add SSH key"
- Paste your key into the "Key" field
- Click "Add key"
- Confirm with password
5.6 Track a new project with git
Given a local directory "some_project"
cd some_project git init git add . git commit
5.7 Creating a new branch
Only works if you configured a private/public key (see above) and if you have permission with a git repository.
Edit the .git file and change an URL to an URI.
url = firstname.lastname@example.org:xxx/yyy.git
url = git://github.com/xxx/yyy
.... don't ask why
Defining a new branch locally
git checkout -b new_branch_name
5.8 Tracking and pushing back files
(this needs permissions)
Create a new branch in the remote repository
git push origin new_branch_name
Track a file, i.e. tell Git that there is a new file and it should watch out for changes. A tracked file is neither in local nor the remote repository so far! Use commit.
git add <file> git something.txt git '*.txt'
- Untracked files cannot be pushed back to the repository
- Once a files is added, it will be "staged", git becomes aware that it should be committed at some point
- Either git add or git commit -a (see below) must be used each time you modify the file...
Remove a file from the current branch
git rm [dir]/file_name
Commit the changes made locally
git commit file
git commit -a
Push the local changes (files) to the remote repository
git push remote-name local-name
- e.g. git push test test
6.2 Short Tutorials
- Subversion (Mediawiki Help)
- Introducing Subversion, IBM Developer Works, by Elliott Harold] (2006) - Explains how to use Eclipse.
- Pro Git book, online version, written by Scott Chaco
- Git for Subversion users
- Git - SVN Crash Course
- A tour of git: basics
- Got 15 minutes and want to learn Git?
- Git Cheat sheet
- Git concepts simplified
6.3 Example instructions for download
- Download from SVN (Mediawiki Help, replaced by GIT, see below)
- Mozilla Source Code (CVS)
- Upgrading Moodle (Using the CVS is a simple method for applying patches, in particular little security upgrades)
6.4 On-line books
- Open Source Development with CVS, 3rd Edition by Karl Fogel and Moshe Bar. (PDF and HTML for older version)
- Version Control with Subversion by Ben Collins-Sussman, Brian W. Fitzpatrick & C. Michael Pilato. There exist several versions.
6.5 Short manuals / cheat sheets
- Subversion Cheat Sheet of Ariejan de Vroom, a.k.a. the SVN Sheet. (useful for experienced users)
- svn checkout. This is the description of the checkout (aka co command) of the Version Control with Subversion book.
- List of RCS systems
- List of revision control software (Wikipedia)
- Quick Reference Guide to Free Software Decentralized Revision Control Systems
- Version-Control Systems for Linux (using local files)
- Lists of clients
- Comparison of Subversion clients (Wikipedia)
- Subversion (software) (Wikipedia)
- Subversion Home Page - Server
- eSvn - a GUI frontend to the Subversion revision system (Cross platform stand-alone client, Unix/win/mac).
6.7 Tutorials for revision control system administrators
(In case you plan to have your own ...)
- Source Control HOWTO by Eric Sink