Revision control system tutorial

The educational technology and digital learning wiki
Jump to navigation Jump to search

Introduction

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
Prerequisites
  • Be able to use command line tools
Moving on
  • Follow up the links below.
Level and target population
  • Beginners
Quality
  • 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


Sometimes we call it "version control". Sometimes we call it "SCM", which stands for either "software configuration management" or "source code management". Sometimes we call it "source control". [...] By any of these names, source control is an important practice for any software development team. The most basic element in software development is our source code. A source control tool offers a system for managing this source code.

There are many source control tools, and they are all different. However, regardless of which tool you use, it is likely that your source control tool provides some or all of the following basic features:

  • It provides a place to store your source code.
  • It provides a historical record of what you have done over time.
  • It can provide a way for developers to work on separate tasks in parallel, merging their efforts later.
  • It can provide a way for developers to work together without getting in each others' way.
Source Control HOWTO, retrieved 18:50, 15 October 2008 (UTC)


Revision control (also known as version control (system) (VCS), source control or (source) code management (SCM)) is the management of multiple revisions of the same unit of information. It is most commonly used in engineering and software development to manage ongoing development of digital documents like application source code, art resources such as blueprints or electronic models, and other projects that may be worked on by a team of people.

Changes to these documents are usually identified by incrementing an associated number or letter code, termed the "revision number", "revision level", or simply "revision" and associated historically with the person making the change. A simple form of revision control, for example, has the initial issue of a drawing assigned the revision number "1". When the first change is made, the revision number is incremented to "2" and so on.

(Wikipedia, retrieved 18:50, 15 October 2008 (UTC))
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.

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.
    • Tortoise SVN is the most popular Windows client. It is integrated with the file explorer.
    • An other good stand-alone Subversion client is eSvn

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

Subversion command-line client

The program is called svn. To install it under Ubuntu, type: 

sudo apt-get install subversion

GIT command-line client

Under Ubuntu, type: 

sudo apt-get install git-core

How to get software from CVS

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" 

:ext:anoymous@test.org:/software/thething

The following will use a password authentication server through user "anonymous" 

:pserver:anonymous@test.org:/software/thething

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:anonymous@cvs-mirror.mozilla.org:/www login

Hit return when it will ask for a password.

Then you can check out something, e.g. 

cvs -d :pserver:anonymous@cvs-mirror.mozilla.org:/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:anonymous@cvs-mirror.mozilla.org:/www argument you also may set the $CVSROOT variable. (Read Environment variable for a how-to).

How to get software from Subversion (SVN)

Subversion protocols

Subversion can be accessed trough several protocols:

  • http://
  • https://
  • svn://
  • svn+ssh://
  • file:///
  • svn+XXX://

The downloading instructions should tell you which one to use.

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: 

svn checkout http://svn.wikimedia.org/svnroot/mediawiki/branches/REL1_13/phase3

To download the development version: 

svn checkout http://svn.wikimedia.org/svnroot/mediawiki/trunk/phase3

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: 

svn checkout http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/NewsChannel/

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

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

Getting help with the command line tool

Besides reading various tutorials, you also may type: 

svn --help

or for a specific topic, e.g. 

svn --help checkout
svn --help co

Authentication

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

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))

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

Updating with GIT

List directories 

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

Example 

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

Example: 

git checkout origin/wmf/1.24wmf22 -b 1.24wmf22
output
....
Branch 1.24wmf22 set up to track remote branch wmf/1.24wmf22 from origin.
Switched to a new branch '1.24wmf22'

Trouble

  • If you get a message like error: you need to resolve your current index first

To get more information, type 

git status

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 -- .
or
git reset
or
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

Checking out older tags

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>

Information

See your configuration 

git config -l

List changes 

git status
  • Tells which files are tracked/untracked
  • Which files are tracked an not committed

Log file of operations 

git log

Log file showing changes (diffs between files) 

git log -p

Show all your remote servers 

git remote -v

Authentication

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 git@github.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:

  • id_rsa
  • id_rsa.pub

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 

https://github.com/settings/ssh
  • Click "Add SSH key"
  • Paste your key into the "Key" field
  • Click "Add key"
  • Confirm with password

Track a new project with git

Given a local directory "some_project" 

cd some_project
git init
git add .
git commit

Creating a new branch

Only works if you configured a private/public key (see above) and if you have permission with a git repository.

List branches 

git branch

Edit the .git file and change an URL to an URI. 

url = git@github.com:xxx/yyy.git

instead of: 

url = git://github.com/xxx/yyy

.... don't ask why

Defining a new branch locally 

git checkout -b new_branch_name

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

Staging

  • 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

or 

git commit -a

Push the local changes (files) to the remote repository 

git push

or (safer) 

git push remote-name local-name
e.g. git push test test

Links

Overviews

Short Tutorials

Subversion
CVS
GIT

Example instructions for download

SVN
CVS
GIT

On-line books

Short manuals / cheat sheets

SVN
GIT

Software links

List of RCS systems
Lists of clients
CVS
Subversion

Tutorials for revision control system administrators

(In case you plan to have your own ...)

Retrieved from "https://edutechwiki.unige.ch/mediawiki/index.php?title=Revision_control_system_tutorial&oldid=76571"