| |
Book_PragSVN
Page history last edited by Anonymous 3 yrs ago
Book Details
Pragmatic Version Control Using Subversion 2nd edtion
- Mike Mason
- Pragmatic Bookshelf
- June 2006
Top
Chap 1 Introduction
Version control (source code control) advantages:
- a project-wide undo button, mistakes are easily rolled back
- allows multiple developers to work on the same code base in a controlled manner
no longer lose changes when someone overwrites the edits made by another team member - keeps a record of of the changes made over time
it's easy to find out who made the change, when, and (with any luck) why. - allows you to support multiple releases of your software at the same time as you continue with the main line of development
no longer a need for the team to stop work during a code freeze just before release - a project-wide time machine, essential for regenerating prior releases
Why Choose Subverion
Versioning for Files, Directories, and Metadata
Atomic Commits and Changesets
- atomic commit: a database transaction analogy when a user commits a change to the repository
making sure that either the entire change is successfully committed or it's aborted and rolled back no half a change whilst someone is making a commit (If your network connection goes down whilst you're committing a change, the change will be rolled back cleanly) - revision: Subversion groups all of your changes into a revision (sometimes called a changeset) and assigns a revision number to the change
grouping changes to multiple files into a single logical unit , able to better organize and track changes
Excellent Networking Support
Cheap Branching, Tagging, and Merging
- Subversion uses an efficient database model to branch and merge files, making these operations quick and painless
True Cross-Platform Support
Top
Chap 2 What is Version Control?
A version control system is a place to store all the various revisions of the stuff you write while developing an application
The Repository
- a central place that holds the master copy of all versions of your project's files
- some version control systems use a database as the repository, some use regular files, and some use a combination of the two
- need to be set on a safe, secure, and reliable machine, and backed up regualarly
- most version control systems today support networked operation
the repository and all its users need not to share a machine or a filesystem developers access the repository over a network, and the repository acting as a server, and the version control tools acting as clients. It doesn't matter where the developers are; as long as they can connect to the repository, they can access all the project's code and its history - The writers of version control systems sometimes have different definitions of what networked means
Subversion uses the client-server model for remote access - What happens if you need to do development but you don't have a network connection to your repository?
Some version control systems are designed for use while connected to the repository, you won't be able to change source code without first connecting Subversion system lets us edit offline and resynchronize the changes when we have network connection - decentralized version control systems: support the notion of multiple repositories instead of a single central repository
Developers can swap sets of changes between the separate repositories are popular when large numbers of developers need to operate semiautonomously (ex: Linux kernel development) Subversion is not decentralized version control system (BitKeeper, Arch, and SVK are)
What Should We Store?
- Simply ask yourself "if we didn't have an up-to-date version of x, could we build, test, and deliver our application?"
If the answer is "no," then x should be in the repository - you should also store your noncode project artifacts under version control, including the project's documentation (both internal and external)
It might also include the text of significant e-mails, minutes of meetings, information you find on the web —anything that contributes to the project - but if a generated file can be reconstituted from other files, then storing it is simply duplication
not disk space wasting problem, but those files need to be regenerated after every change to be up-to-date, that could be redundant Moreover, if we forget to update it and check it back in, we've now got misleading documentation in our repository
Working Copies and Manipulating Files
Projects, Directories, and Files
Where Do Versions Come In?
- Version control system stores every version that has ever been checked in.
If you check out a file, edit it, and then check it back in, the repository will hold both the original version and the version that contains your changes - In reality, most version control systems store the differences between versions of a file, rather than complete copies of each revision
- Subversion stores the full text for the newest revision of a file, as well as cleverly picking historical revisions to store in full.
This helps minimize disk space requirements while keeping updates and checkouts fast - two common numbering schemes for version control systems:
- file-specific numbering:
the first revision of a file is named 1.1. When a change is checked in, the file is given the number 1.2, and so on CVS uses this scheme, so people often look at the revision number of a file to try to gauge how much activity is occurring in the file or how much has changed over a period of time - repository-wide numbering scheme:
the entire repository starts at revision 0, and checking in a change increases the repository revision number to 1, then 2, and so on Subversion uses this numbering scheme, which turns out to be useful for referring to changes once they've been committed (but need to use Subversion's log command to examine the history to look for changes in a particular file or group of files, not like CVS) (but powerful when check out all of the source code of a system exactly as it appeared two months ago)
Tags
- tag: let you assign Tags names to a group of files (or directories or an entire project) at a particular point in time
- better at remembering names such as PreRelease2 rather than numbers such as r347
- a great way of keeping track of significant events in the life of your project's code.
Branches
- trunk: the main line of the development, the common code base that co-workers work with
- branch:allows you to create multiple parallel future
A bit like the hackneyed device in science fiction stories where some event causes time to split. From that point forward there are two parallel futures. Some other event occurs, and one of these futures splits too 
The team working on the release will have a stable code base to polish and ship. In the meantime, the main group of developers can continue making changes to the main line of code; there's no need for a code freeze while the release takes place. And when customers report problems in the release, the team will have access to the code in the release branch so they can fix the bugs and ship updated releases without including any of the newly developed code from the trunk. - A branch is almost like having a totally separate repository:
people using that branch see the source code it contains and operate independently of people working on other branches or the trunk. Each branch has its own history and tracks changes independently of the trunk (but if you look back past the point where the branch was made, you'll see that the branch and the trunk become one) - using branches:
- need not to freeze new development while the release is being generated, the rest of the team will not be idle
- can still keep track of changes to these branches, merge them with trunk, roll back just like trunk
- Branches are stored as named directories within Subversion; you create a branch simply by copying the trunk to a new location
- Subversion's internals use lazy copies to make the copying process efficient, and these lazy copies are the basis of Subversion's tagging support too.
- lazy copies: Whenever you copy a file or directory, Subversion simply stores a link to the original
When you make a change to the copy, Subversion records those changes as differences against the original can very quickly copy large trees of files using almost zero space, ideal for branches and tags - You should avoid excessive branching
Even though branches might seem like a cheap way to hedge your bets during development, they have significant costs when you need to merge changes between branches - Bear in mind that the need to create multiple branches, especially for parallel lines of development rather than releases,
may be a sign that something is going wrong (should divide more independent modules, redesign the architechture)
Merging
Locking Options
Imagine two developers, Fred andWilma, working on the same project
Each has checked out the project's files onto their respective local hard drives,and each wants to edit their local copy of File1.java
What happens when they come to check that file in?
Need some form of conflict resolution system:
- strict locking:
All files that are checked out are initially flagged as being read-only, you can't edit or change them If you want to edit the file, you need to ask the repository's permission first If no one else is editing that same file, then the repository gives you permission and changes the permissions of your local copy of the file to be read/write You can then edit After you've finished your changes and checked the file in, your local copy reverts to being read only, and it becomes available for other folks to edit - optimistic locking:
Every developer gets to edit any checked-out file: the files are checked out in a read/write state However, the repository will not allow you to check in a file that has been updated in the repository since you last checked it out Instead, it asks you to update your local copy of the file to include the latest repository changes before checking in You then resolve the conflict part and check the file in again, then successfully merge both changes of your local copy and repository (Instead of simply overwriting all your hard work with the latest repository version of the file, the version control system attempts to merge the repository changes with your changes)  (Click to enlarge)
Why Subverision choose optimistic locking?
- conflicts rarely arise
in practice, the normal ways of dividing work on a team mean that people work on different areas of the code; they don't bump into each other that often - when they do need to edit the same file, they're often working on different parts of it
- no need to wait for other to finish and check in before proceeding
(Subversion 1.2 introduced optional file locking, using a simple file property you can ask Subversion to enforce strict locking on individual files)
Configuration Management (CM)
Top
Chap 3 Getting Started with Subversion
- This chapter will show you how to create and work with a live Subversion repository.
You'll be learning the basic steps in using Subversion whilst maintaining a trivial project. - Subversion ships with a command-line client, but there are a variety of third-party tools for interacting with your repository.
TortoiseSVN integrates with the Windows Explorer, for example, and some IDEs now include Subversion support.
Installing Subversion
Go to http://subversion.tigris.org/ to download and install Subversion
Checking If Subversion Is Installed
- svn --version: check if the Subversion client is installed correctly
- svnadmin --version: see if the Subversion administration tools are installed
Creating a Repository
| mkdir /home/mike/svn-repos svnadmin create /home/mike/svn-repos |
for now you can safely treat the repository directory and its contents as a black box.
Creating a Simple Project (Repository)
| mkdir tmpdir cd tmpdir (create project files) svn import -m "importing Sesame project" . file:///home/mike/svn-repos/sesame/trunk |
- import: tells Subversion we want to import some files to our repository
- -m option: allows you to associate a message with this import
(It's a good idea to use a log message indicating what kind of import you've performed) - . : tells Subversion to import the contents of the current directory, tmpdir, into the repository
- file:///home/mike/svn-repos/sesame/trunk:
a repository URL describing where we want to import the files Here we're telling Subversion to look on the local filesystem for the repository in our svn-repos directory and to import into /sesame/trunk inside it.
Starting to Work with a Project (Working Copy)
- Decide where to put the working copies of the files on your local machine.
- Check the project out of the repository into that location.
| mkdir /home/mike/work svn co file:///home/mike/svn-repos/sesame/trunk sesame |
- co: tells Subversion that we want to perform a checkout
- file:// URL: specifies which repository we want to check out from
- sesame: where we want to put our working copy
We'll then be working with these copies of the files (/home/mike/work/sesame/trunk), because these are the ones that are being managed by Subversion.
After checking that they look correct, we can go ahead and delete the original copies in our temporary directory (tmpdir).
Making Changes
| sesame> svn status Day.txt M Day.txt |
- svn st: get the status of one or more files
- M: Subversion recognizes that this file has been modified locally (and that these changes have not yet been saved in the repository)
| sesame> svn diff Day.txt Index: Day.txt =================================================================== --- Day.txt (revision 1) +++ Day.txt (working copy) @@ -3,3 +3,5 @@ wednesday thursday friday +saturday +sunday |
Updating the Repository
| sesame> svn commit -m "Client wants us to work on weekends" |
- svn ci: save any changes we've made back to the repository
- -m: attach a meaningful message to the changes
- it will cleverly decide which file has changed and only send it to repository
| sesame> svn log Day.txt --------------------------------------------------------- r2 | mike | 2004-09-08 21:54:19 -0600 (Wed, 08 Sep 2004) Client wants us to work on weekends --------------------------------------------------------- r1 | mike | 2004-09-08 21:50:13 -0600 (Wed, 08 Sep 2004) importing Sesame project --------------------------------------------------------- |
| sesame> svn log --verbose Day.txt --------------------------------------------------------- r2 | mike | 2004-09-08 21:54:19 -0600 (Wed, 08 Sep 2004) Changed paths: M /sesame/trunk/Day.txt Client wants us to work on weekends --------------------------------------------------------- r1 | mike | 2004-09-08 21:50:13 -0600 (Wed, 08 Sep 2004) Changed paths: A /sesame A /sesame/trunk A /sesame/trunk/Day.txt A /sesame/trunk/Number.txt importing Sesame project --------------------------------------------------------- |
- svn log -v: tell you exactly what changed with each revision
- using svn log without any other arguments produces a log for the current directory and any subdirectories
- Whenever you change the repository by importing files, committing changes, or copying things around, you need to enter a log message.
If you don't specify the -m option, Subversion will try to open an editor for you to type in a log message - you can set environment variables differently depending on the shell you're using to set that editor.
Try looking at .profile, .bashrc, or .cshrc in your home directory for existing environment variables, and then add a new one
Mixed Revision Working Copies
When Worlds Collide
| aladdin> svn diff -rHEAD Number.txt Index: Number.txt =================================================================== --- Number.txt (revision 3) +++ Number.txt (working copy) @@ -3,5 +3,3 @@ two three four -five -six |
- -rHEAD: the most recent revision in the repository
- If we hadn't specified the -r flag, Subversion would compare our local copy of Number.txt against the repository version that was checked out to produce it
Conflict Resolution
| sesame> svn commit -m "Zero needs emphasizing" Sending Number.txt svn: Commit failed (details follow): svn: Out of date: '/sesame/trunk/Number.txt' in transaction '7' |
1. the changes didn't overlap:
2. changes overlap (conflict):
| ZERO <<<<<<< .mine ichi ======= uno >>>>>>> .r6 two three four five SIX |
- a breakdown in communication (how to resolve this conflict) (Subversion leave the resovling problem to people)
- svn resolved: Having removed the conflict markers, we can tell Subversion we've resolved the conflict
- svn ci again
However, it's also worth noting that Subversion is not a mindreader.
It might happen that two people fix the same bug in two different ways.
If these changes don't conflict at the source code level, Subversion will happily accept both,
even though it may make no sense to have both fixes in the same code.
Top
Chap 4 How To...
The remaining chapters in this book present a simple way to organize your versioncontrol system and
a set of basic practices for doing the everyday things a team needs to do.
Our Basic Philosophy
Every team should be using version control—all the time, and for everything they produce.
So we have to make it:
Important Steps When Using Version Control
- Before you start, you need to establish an effective and secure way to access your repository.
- Once you’ve gained access, there is a simple set of Subversion commands that you'll be using daily.
- Each project that your company develops must be stored in a distinct directory within the Subversion repository.
You should be able to check out a project's complete source from a single point. - If projects contain subcomponents that can be worked on in isolation, or if you intend to share components between projects,
these components should be stored as projects in their own right and included as an external resource in other projects. - If your project incorporates code from third parties (vendors, or perhaps open-source projects) you need to manage this as a resource.
- Developers should use branches to separate the main line of development from code lines that have different life cycles,
such as release branches and major code experiments. Tags are used to identify significant points in time, including releases and bug fixes.
Top
Chap 5 Accessing a Repository
In this chapter we'll discuss the 3 main ways you can make an existing repository available over the network,
what they mean for a user accessing a repository, and the pros and cons of the various access mechanisms.
Network Protocols
- repository URL: included both a definition of where the repository was and also what path inside the repository we were interested in
- Once we had a working copy we didn't need to keep using the repository URL, since Subversion remembers where our working copy came from.
Scheme
Specifies how we locate the repository:
svn
| work> svn co svn://olio/sesame/trunk vizier |
- The easiest way to network a repository
- Subversion comes with svnserve, a small server that listens for network connections,
allows repository access over the network, and supports simple authentication of users. - svnserve is probably most suitable for teams on a private LAN who want to get going quickly
- If Subversion doesn't let you commit any changes using svn scheme, your administrator may has forgotten to enable write access to the repository
(it's read-only by default). - There is an authentication mechanism to ask for a username and password when you try to commit a change
svn+ssh
| work> svn co svn+ssh://olio/home/mike/svn-repos/sesame/trunk princess |
- svnserve's drawbacks:
- Subversion solves both of these security problems by leveraging the Secure Shell (SSH).
- SSH employs strong encryption to protect the contents of a client-server session.
- Subversion needs an SSH client installed on your machine in order for you to access a repository using svn+ssh
If you're on Windows, Putty is an excellent SSH client (H 注： 其實 PieTTY 也不錯 :p) If you're using TortoiseSVN you don't need to worry about installing an SSH client since Tortoise comes with TortoisePlink.
http
| work> svn checkout http://olio.mynetwork.net/svn-repos/sesame/trunk sesame |
- Subversion can also host a repository over the web by using the Apache web server.
- You can host a repository using standard http and https and leverage any of the authentication mechanisms already supported by Apache
- Apache provides a wealth of authentication options for users:
Choosing a Networking Option
svn
- If your team is on a reasonably secure LAN, or even a larger network connected by a VPN
- a quick way to get up and running with Subversion
- have some administrative overhead when adding new users or changing passwords, but this should be offset by the easy startup
- Subversion 1.3 added directory-based authorization to svnserve
svn+ssh
- If you already have existing SSH infrastructure in place
- get strong crypto protecting your connections
- take advantage of all of the key management and authentication options that SSH provides
http
- If you want to host a repository over the Internet, leverage Apache's wide range of authentication mechanisms
- able to use SSL and client-server certificates for encryption and verifying you're really talking to whom you think you're talking to
- able to authorize users using a Windows domain, LDAP, or any other authentication mechanism that Apache supports
- able to be much more precise about which parts of a repository users have access to, by leveraging the mod_authz_svn Apache module
- Using Apache on standard HTTP ports also means fewer holes need to be opened on your firewalls
Top
Chap 6 Common Subversion Commands
The commands and techniques in this chapter should handle 90 percent of the work you do with Subversion.
Checking Things Out
- svn checkout (svn co): gets Subversion to create a new working copy from a directory stored in the repository
in the simplest form (svn co svn://xxx/yyy), the checkout command creates a working copy in a directory with the same name as the repository directory can use an extra argument (svn co svn://xxx/yy project_name) to specify the name of the directory Subversion should use for your working cop - svn co -r 6 svn://xxx/yy: By default, Subversion checks out the latest revision stored in the repository.
If you'd like an older version, use the -r option to specify the revision number or date you'd like
Keeping Up-to-Date
- svn update (svn up): used within a working copy and brings all the files in the directory (and its subdirectories) up-to-date with the repository.
- You can choose to update just part of your checked-out tree.
If you issue the command in a subdirectory of a project, then only files at or below that point will be updated. but it leaves you exposed to working on an inconsistent set of files. - svn up build.xml src/ test/: specify one or more individual files or directories to update
- Incorporate others' changes into your working copy fairly frequently; the longer you leave it, the bigger the hassle of fixing any conflicts.
- During the update process, Subversion will show the status of each file:
- A: added a file to your working copy in order to bring it up-to-date with a new file in the repository
- U: Subversion hsa updated your working copy of the out-of-date file to the new version
- D: Subversion has deleted a file from your working copy because the file has been removed from the repository
- G: a file that was out-of-date in your working copy, which you had modified locally.
Subversion successfully merged the changes from the repository with your local modifications. - C: a file that was out-of-date in your working copy, which you had modified locally.
Subversion tried to merge the changes from the repository with your local modifications but encountered a conflict. You'll need to resolve the conflict before you can check in. - Subversion is actually printing two columns of information. The second column indicates changes to a file's properties, rather than to a file itself.
Adding Files and Directories
Properties
- Subversion can also store metadata associated with each file (and directory) in the repository.
- property: Subversion calls this metadata properties and manages changes to properties in the properties same way as a file's contents
- should be aware of a few special properties that change the way Subversion behaves
Manipulating Properties
| svn propset checked-by "Mike Mason" Number.txt svn propedit checked-by Number.txt svn proplist Number.txt svn propget checked-by Number.txt |
(checked-by there is a user-defined property)
Keyword Expansion
The philosophical problem of keyword expansion
Ignoring Certain Files
- Most of the time your working copy will contain both files you want under version control (source code, build scripts, graphics for your application, and so on)
and files that you're happy to have lying around but that don't need to be stored in the repository (temporary files, compiled code, and logfiles). - Some Subversion commands, notably svn status, svn add, and svn import assume you're interested in all the files in your working copy.
For example, svn status displays files that aren't under revision control in case you've forgotten to add them - This extra output for files you really don't want Subversion to worry about can be annoying
- Fortunately, there's an easy way to avoid these problems: setting the svn:ignore property on a directory specifies files you'd like Subversion to ignore.
- Once your changes are committed, everyone will receive the update to the svn:ignore property on the directory, causing Subversion to ignore files in their working copies too.
- The svn:ignore property applies only to the contents of a particular directory; it doesn't apply recursively to subdirectories.
Setting End-of-Line Style
- denote the end of a line of text:
- Windows: a carriage-return followed by a linefeed (CRLF)
- Unix and Mac OS X: simply a linefeed (LF)
- older versions of Mac OS: a plain carriage-return (CR)
- Opening a Unix-formatted file using Windows' Notepad, for example, produces a file with lots of little squares in it instead of newlines.
Opening a Windows-formatted file in Unix might result in lots of ˆM characters at the end of each line. - Subversion stores all files using a binary format in the repository
Unless you ask it to, Subversion will never convert a file's line-ending style - Subversion will do a conversion for you if you set the svn:eol-style property to one of the values in the following:
- native: Subversion will translate end-of-line characters to whatever the client operating system expects, and so will use CRLF on Windows and LF on Unix
- CRLF: will always use CRLF as an end-of-line marker when it creates files in the working copy
- LF: will always use LF as an end-of-line marker on the client
- CR: will always use CR as an end-of-line marker on the client
Book_PragSVN
|
|
Tip: To turn text into a link, highlight the text, then click on a page or file from the list above.
|
|
|
|
|
Comments (0)
You don't have permission to comment on this page.