ClassRooms/SvnBasics
From Wiki.ooo4kids.org
Subversion basics
Back to ClassRooms
 |
Languages: English |
Contents |
A lesson about SVN, aka Subversion will be available here.
Information for tutors
| Time | 30 minutes (presentation + questions) |
| Pre-requisites | Must be able to use the Bash shell. Subversion have to be installed and working. |
| Associated tools | Terminal |
| Difficulty level | 
|
Goal
=> Learn the SVN essentials (basic usage on the client side)
- This course will teach a student how to:
- Download OOo4Kids / OOoLight sources from the Adullact repository using the version control system Subversion.
- Find the current revision
- Update the sources
- Create a diff file for patching purposes
- Extract a given changeset (between two revisions)
- Reverse a change in the sources
Introduction
Subversion, commonly abbreviated as SVN, is a centralized versioning control system like CVS. This is the tools we'll use in this class room.
We'll use Subversion until EducOOo switches to Global Information Tracker (somewhere in 2010).
We assume that subversion is installed. If not, follow the instructions below:
- Linux: Use the distribution's package management tools.
- Mac OS X (10.4 and later) : Subversion is normaly shipped with XCode. If it's not available in your XCode version, install it using the Darwin port or Fink.
- Windows : Install Subversion using Cygwin and the correct repository.
How things work
- Repository : The website from where the sources are downloaded. OOo4Kids and OOoLight sources are hosted by Adullact.
- Branch : A complete version of the sources. For example : stable, trunk, developement.
- Commit : Everytime a developer do changes, a new revision of the sources is counted as a version. The source history is kept with version numbers.
- Revision : A full version of a branch after a given commit.
- Changeset: Differences with all changes between two given revisions.
- Checkout : The performed operation when downloading a revision of the sources, or a part of the tree. Usually abbreviated with the "co"option.
Download OOo4Kids sources from Adullact (main) repository
- Open a Terminal;
- Change to a prefered directory;
- and verify that you have more than 12 GB available for the full build.
Then, do :
svn co -r1206 svn://svn.adullact.net/svnroot/ooo4kids1/trunk OOo4Kids1.2
With a fast connection, the source should be ready in ~20 minutes. The $SRC_ROOT indicates that the sub directory containing the complete tree will be named OOo4Kids1.2
Notes:
- "co" is equivalent to "checkout"
- OOo4Kids 1.2 is r1206
- To find the current revision, look at CIA-vc OOo4Kids project
- the supported locales are : ar, de, es, el, en-US, fi, fr, it, nb, nl, pt, sl, zh-CN and zh-TW.
Important: If you choose another revision, things might not work as expected.
Update the sources
Imagine a fix have been committed and that you know this is the latest revision. The command to update the sources are:
cd $SRC_ROOT svn up aModule
Note: You must rebuild the modified modules, deliver, package, etc to see the last changes applied.
Retrieve the current revision
This can be achieved, from anywhere in the tree, e.g. doing:
cd $SRC_ROOT svn info
e.g.
truc:~/Desktop/r910/redland ericb$ pwd /Users/ericb/Desktop/r910/redland
We are now in the "redland" module. Let's check the revision:
truc:~/Desktop/r910/redland ericb$ svn info Path: . URL: svn://svn.adullact.net/svnroot/ooo4kids1/trunk/redland Repository Root: svn://svn.adullact.net/svnroot/ooo4kids1 Repository UUID: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (hidden) Revision: 910 Node Kind: directory Schedule: normal Last Changed Author: ericb Last Changed Rev: 256 Last Changed Date: 2010-01-14 09:35:19 +0100 (Thu, 14 Jan 2010)
Create a diff
Imagine that you implemented a nice feature in several modules, but you prefer to let the other devs test it before implementing the changes into the final code. Just create a patch and other devs will be able to try it. E.g. you made a change in both sfx2, vcl, scp2 and svtools.
To create the patch, go to the $SRC_ROOT, and do this:
svn diff sfx2 > my_feature.diff svn diff vcl >> my_feature.diff svn diff scp2 >> my_feature.diff svn diff tools >> my_feature.diff
Or in one pass (assuming you are using the Bourne Again Shell (aka bash):
rm -f my_feature.diff for folder in sfx2 scp2 vcl tools ; do svn diff $folder >> my_feature.diff done
Remarks:
- By default svn diff uses the -u (unified) format for the file, meaning 3 lines of context before and after every change.
- The order for the changes is not important, just take care to not add the same changes twice.
Reverse a change
Imagine that you did a incorrect change in sw. To reverse it, simply do this:
cd $SRC_ROOT svn diff sw | patch -R -p0
Important: There's no need to be connected as Subversion metadata holds all the necessary information to retrieve the same content as the current revision.
Extract a given changeset
Imagine that you want to extract the diff corresponding to the changes between revision X and X+1
The command is:
svn diff -cr#number svn://svn.adullact.net/svnroot/ooo4kids1/trunk
For example:
truc:~/Desktop/r910 ericb$ svn diff -cr908 svn://svn.adullact.net/svnroot/ooo4kids1 Index: trunk/solenv/inc/minor_OOoLight.mk =================================================================== --- trunk/solenv/inc/minor_OOoLight.mk (revision 907) +++ trunk/solenv/inc/minor_OOoLight.mk (revision 908) @@ -1,5 +1,5 @@ -RSCVERSION=1.00 +RSCVERSION=1.01 RSCREVISION=1.00m12(Build:001) BUILD=10 -LAST_MINOR=r888 +LAST_MINOR=r910 SOURCEVERSION=OOL101 Index: trunk/solenv/inc/minor_OOo4Kids.mk =================================================================== --- trunk/solenv/inc/minor_OOo4Kids.mk (revision 907) +++ trunk/solenv/inc/minor_OOo4Kids.mk (revision 908) @@ -1,5 +1,5 @@ -RSCVERSION=1.00 +RSCVERSION=1.01 RSCREVISION=1.00m12(Build:001) BUILD=10 -LAST_MINOR=r888 +LAST_MINOR=r910 SOURCEVERSION=O4K101
Important: When the change affects a image (e.g. a PNG file), the content is not shown.
e.g. :
truc:~/Desktop/r910 ericb$ svn diff -cr907 svn://svn.adullact.net/svnroot/ooo4kids1 Index: trunk/sysui/desktop/icons/hicolor/48x48/apps/OOoLight/printeradmin.png =================================================================== Cannot display: file marked as a binary type. svn:mime-type = application/octet-stream ... partial diff (because a lot of changes in this commit)
Summary of the most important Subversion commands
References:
- SvnBook Red Bean
- svn help
svn co
Download a file, module or the full tree
- svn co -r#number svn://svn_repository/theBranch aFolderName
- co or checkout
- -r#number : -r for revision, and #number is the exact number
- svn://svn_repository : svn protocol, svn_repository
- theBranch : the name of the branch to be downloaded. e.g. trunk, dev, stable ... and so on.
- aFolderName : i.e. the $SRC_ROOT, or the name of the folder where the sources will be put.
svn diff
Create a diff
svn up
Update the current dir, including all subdirs (with metadata in .svn sub directories)
With the Subversion repository having 1 revision of the project source code with all of its metadata and directory structure, the projects team of developers should be able to modify important files that can be imported to subversion without the developers local copy of all source code files and directories.
For example, after the creation of a new Subversion project, the first revision was imported to the server.
svn import ProjectSourceCode URL ... ... Adding ProjectSourceCode/SubFolder1/SubFolder2/metadata 1 Adding ProjectSourceCode/SubFolder1/SubFolder3/dlgass.cxx ... ... Committed revision 1.
So from this point in the project any developer that updates a source code file or metadata does not need to import their whole local project current directory to Subversion. It would take up memory space with duplicate files.
"Metadata 1" is a text file describing a project log report from a group of developers working with a local project with a Subversion Server repository.
Software Developer #1, adds 2 new records to the metadata log file from a local copy.
view "metadata 1"
Date Time Username Message
Oct 26th 2010, at 6:22pm | JohnDoe | gdb classrooms are extremely important in software development education.
Oct 27th 2010, at 1:12pm | JohnDoe | This metadata was updated within a directory substructure.
Software Developer #1, then adds and commits the new version of the metadata to the Subversion project.
svn add "metadata 1" svn commit Sending framework/metadata 1 Transmitting file data . Committed revision 2.
Software Developer #2, exports the repository from Subversion.
svn checkout -r HEAD URL
Software Developer #2, then adds a new line(record) to the metadata log report.
view "metadata 1" .... .... Oct 27th 2010, at 1:24pm | Mikezy | Testing commit commands and conflicts
Software Developer #2, then adds and commits the new version of the metadata to the Subversion project.
svn add "metadata 1" svn commit Sending framework/metadata 1 Transmitting file data . Committed revision 3.
Software Developer #2 gets a version conflict, with the 1st developers metadata file.
svn update "metadata 1"
Conflict discovered in 'metadata 1'.
Select: (p) postpone, (df) diff-full, (e) edit,
(mc) mine-conflict, (tc) theirs-conflict,
(s) show all options: tc
The second (#2)developer chooses the first (#1)developers version of 'metadata 1' over their own.
Software Developer #1, then checksout the Subversion repository again.
svn checkout -r HEAD URL
Software Developer #1 adds, another line to the metadata log report.
view "metadata 1" .... .... .... Oct 27th 2010, at 1:24pm | Mikezy | Testing commit commands and conflicts Oct 27th 2010, at 1:33pm | John Doe | Then "meta data 1" was checked out from the Subversion repository by John.
Software Developer #1, then adds and commits the new version of the metadata to the Subversion project.
svn commit "metadata 1" Sending metadata 1 Transmitting file data . Committed revision 4.
Software Developer #2, adds another line to the metadata log report at the same time.
view "metadata 1" .... .... .... Oct 27th 2010, at 1:24pm | Mikezy | Testing commit commands and conflicts Oct 27th 2010, at 1:33pm | John Doe | Then "meta data 1" was checked out from the Subversion repository by John. Oct 28th 2010, at 7:15pm | John Doe | Upgraded version of the Software project has been archived. Oct 27th 2010, at 5:00pm | JJ| pushing some changes
Software Developer #2, then adds and commits the different version of the metadata to the Subversion project.
svn update "metadata 1"
Conflict discovered in 'metadata 1'.
Select: (p) postpone, (df) diff-full, (e) edit,
(mc) mine-conflict, (tc) theirs-conflict,
(s) show all options: tc
G metadata 1
Updated to revision 5.
The second (#2)developer again chooses the first (#1)developers version with the svn option "tc" 'their conflict' meaning do not overwrite with the uploading local copy of the metadata file, keep the current subversion repositories copy of the metadata as it is.
Software Developer #1 adds, another different version of the metadata log report.
view "metadata 1" .... .... .... Oct 27th 2010, at 1:24pm | Mikezy | Testing commit commands and conflicts Oct 27th 2010, at 1:33pm | John Doe | Then "meta data 1" was checked out from the Subversion repository by John. Oct 28th 2010, at 7:15pm | John Doe | Upgraded version of the Software project has been archived.
Software Developer #1, then adds and commits the new version of the metadata to the Subversion project.
svn update "metadata 1"
Conflict discovered in 'metadata 1'.
Select: (p) postpone, (df) diff-full, (e) edit,
(mc) mine-conflict, (tc) theirs-conflict,
(s) show all options: mc
G metadata 1
Updated to revision 6.
Software Developer #1, has now overwritten their changes that were currently saved on the subversion repository, with svn option "mc" 'mine conflict' meaning overwrite with the uploading local copy of the files as the most current version of the metadata file, thereby updating metadata within a directory structure of a Subversion structure. For an application of Subversions svn update.
svn info
As part of a software development group you need to find the status of your organizations Subversions repository. For example you need the status of the project, meaning a local directories connection to the Subversion Server, with information on the latest revision, the username that pushed it to the repository, and when the latest revision was pushed to the repository. cd into your local Subversion directory, then try
svn info
Path: . #from this locally set up directory connected to the subversion repository,
#here we see that the command was run from within the local subverson directory.
URL: https://someSubversionServerURL
Repository Root: https://someSubversionServerURL
Repository UUID: #Universal-Unique-IDentifier #used by clients to identify the subversion repository,
#that is created by the administrator at setup.
Revision: 15 #the number of revisions pushed revisions.
Node Kind: directory #the latest revision that was imported (revision 15) was within a directory.
Schedule: normal
#who was the author, what was the last revision number, and what was the date & time of the revision.
Last Changed Author: someUsername
Last Changed Rev: 15
Last Changed Date: 2010-10-19 10:25:49 -0700 (Tue, 19 Oct 2010)
If you attempt to get svn info not from within the directory that was setup by the first connection to Subversion, could give show an initial error.
svn: '.' is not a working copy
More precisely, it means there is no .svn subdir (containing metadatas, history and so on) in the current directory.
svn diff -cr#number
Extracts a given revision. "c" means changeset.
svn diff -r#number1:#number2 URL
Extracts the changes between revision #number1 and revision #number2
Extract incremental diffs between 2 given révisions
You can us bash shell scripts to extract incremental diffs between two given revisions of the repository.
The example below, will produce :
change_from_r842_to_r843.diff, change_from_r843_to_r844.diff .... until change_from_r849_to_r850.diff
You can copy paste the file below (please respect the copyright and the license) and adapt and use it for your needs:
#!/bin/bash
# Author : Eric Bachard, february 2012
# License : GPL v2
# for debug purpose
#set -x
URL=svn://svn.adullact.net/svnroot/ooo4kids1/trunk
REVISION_START=842
REVISION_END=850
for (( i=$REVISION_START ; i<$REVISION_END ; i++ ))
do svn diff -r${i}:r$(( $i + 1 )) $URL > change_from_r${i}_to_r$(( i+1 ))".diff"
done
Tip : don't forget to chmod ug+x the file if you want to use it in a terminal
