Revision Control by George Hernandez

Revision control is the management of changes to documents, programs, and other items stored as computer files.

This page has some general stuff about revsion contol, but it also has notes specific to Mercurial and related items.

Intro

What is revision control? Revision control manages changes to documents, programs, and other items stored as computer files. Revision control manages who made which changes when and why to what. The more complex or collaborative a project, the greater the need for revision control.

While revision control is most commonly associated with program code, people actually experience and do "revision control" all the time: writing documents, retelling stories, rendering and remaking songs, mashing recipes, crafting pictures, and so on.

A change in the trunk is a branch:

(t0: [T], t1: [T, TB])

If the branch merges back to the trunk, then it was a transient branch and it is the same as a revision to the trunk. Most revisions are unnamed transient "branches": A change and a commit. Named branches usually persist beyond several commits.

(t0: [T], t1: [T, TB], t2: [TB]) =
(t0: [T],              t2: [TB])

A discontinued branch leaves the trunk untouched. This is like a rollback:

(t0: [T], t1: [T, TB], t2: [T]) =
(t0: [T],              t2: [T])

If a branch is not expected to merge with the trunk then you fork into 2 trunks. (Although even a fork could be merged too.):

(t0: [T], t1: [T, TB], t2: [T, TB])

A repository is a history of the state of trunk, its branches, and the merges/discards of branches. If there's a fork, then the history from that point on is not shared between the repositories.

If a set of changes (aka changeset), has no child changesets, then it is a head changeset. The tip is the most recently changed head.

Here are application versions in revision control lingo:

An unsupported old version. A discontinued branch.
A supported old version. An old trunk that is still supported but not generally developed with new functionality.
Versions near the tip of the trunk, from oldest to newest:
- The current stable version. The latest well tested released version.
- A release candidate version. Almost done testing, almost ready for release.
- Beta version. Undergoing testing.
- Alpha version. Just started undergoing testing.
- Development version. Not well tested.

Revision control is a concept and there are nuances and variants, hence there are many names and acronyms:

Revision Control Software/System (RCS). Distributed RCS (DRCS) uses a peer-to-peer approach instead of a centralized repository.
Version Control Software/System (VCS)
Software Configuration Management (SCM)
Source Code Managment (SCM)
Source Code Version (SCV)

Some major version of revision control software that are gratis and libre:

Concurrent Versions System (CVS). Aka Concurrent Versioning System. Released 1990.
Subversion (SVN). Released 2000.
Git. Released 2005.
Mercurial. Released 2005. I use this.

Mercurial

Mercurial Intro

One of the 1st things you do after install is modify mercurial.ini with your username and editor preference. The ini file is in ~/.hgrc or %USERPROFILE%\Mercurial.ini.

username = First Last <youremail@example.com>
editor = "C:\Program Files (x86)\Notepad++\notepad++.exe"

In Mercurial a repository is a working directory of files and subdirectories, that also has a special directory named .hg, which contains metadata about the repository especially the RCS history of the repository. The working directory has a snapshot of the project. You can modify the hgrc file there to store common variables used in your mercurial commands.

Some of my notes are based on work from tutorials and are written as if done from the command line interface (CLI), commonly $ in Unix or C:\dir> in Windows. Note that # starts a comment.

Use case: Log keeping

$ hg init project
$ cd project
# Add files
$ hg add # Tell Mercurial to track all files
# Do some changes
$ hg cp # Copy files or folders
$ hg mv # Rename/move files or folders
$ hg st # See which files changed
$ hg diff # See the changes
$ hg ci # Save changes
$ hg log # See history.

Use case: Lone developer with nonlinear

If bug in earlier revision, then either fix in current code, or fix in history and resolve to future revisions. Here are steps for the latter.

$ hg update -r 3 # Switch to a previous version.
$ hg identify # Identify version
# Fix bug
$ hg ci
# Now propagate fix into descendants, copies, etc:
$ hg merge
$ hg resolve --list # Get list of files with conflicts
$ hg resolve conflicting_file # Resolve conflicts 1 by 1.
$ hg resolve --mark conflicting_file # Mark as resolved.
$ hg ci

Use case: Separate features

$ hg clone project project1 # Clone to a temp repo for messing around 
$ cd project1
# Do some changes and commits
$ cd ../project
$ hg incoming ../project1 # See what the differences are
$ hg pull ../project1 
# Merge, resolve, and commit as necessary.
# You can rollback as long as you haven't done a ci or pull
$ hg rollback
$ hg ci -m "I rolledback because ..."

Use case: Sharing changes

# OPTION 1: You can pull from OTHER wtih a URL:
$ hg serve # Start the built in hg webserver at OTHER
$ hg pull http://192.168.0.15:8000 # your IP, but port 8000 by default

# OPTION 2: You can export as a patch then import:
$ hg export > changes.diff # Export at OTHER
$ hg clone project project1 # Clone project for a sandbox
$ cd project1
hg import changes.dff
# Merge, resolve, and commit as necessary.
$ cd ../project
$ hg pull ../project1

# OPTION 3: Use a service like BitBucket
# Get an account at BitBucket.
# Create an empty repo at BitBucket. EG: proj
hg clone https://yourusername@bitbucket.org/yourusername/proj
# Add and ci files to local proj
hg push https://yourusername@bitbucket.org/yourusername/proj
# Pull and push later as needed
hg pull https://yourusername@bitbucket.org/yourusername/proj

Use case: Syncing with OTHER (partner or central) repository

# Assume OTHER has latest version:
$ hg pull OTHER # Get latest branch from OTHER
$ hg update # Sync your local branch with OTHER branch
# Make some changes and commit locally
# Now you probably have the latest version
$ hg pull OTHER # Get from OTHER in case it has also changed
# Merge, resolve, and commit as necessary.
$ hg push OTHER # Push your local branch to OTHER

Use case: Backing out bad revisions

# Revert to unmodified state since the last commit.
$ hg revert -a

Use case: Collaborative feature development

# A named branch allows ci, pull, push, merge as if it were a separate repo
$ hg branch myBranch # Make a branch
# Make changes
$ hg ci # Branch does not exist until ci

# If someone else wants to work on the branch:
$ hg update myBranch
# Make changes
$ hg ci 

# When the branch is ready to join the trunk:
$ hg update default
$ hg merge myBranch
$ hg ci
$ hg update myBranch
$ hg ci --close-branch -m "finished"

Use case: Tagging revisions

$ hg tag -r 3 v0.1 # Apply a tag
$ hg tags # See all tags
$ hg update v0.1 # Update the working directory to the named tag

Use case: Removing history

# I'm skipping this one for now.

Command Notes

$ hg help 
# For a command: hg COMMAND -help
# Commands usually use this syntax: hg COMMAND [OPTIONS] [USUAL PARAMEMTERS]
# Additional help topics include:
$ hg help config # Configuration files
$ hg help dates # Date formats
# Faves include:
## "-i" # Within i days of today
## "2011-07-08 13:14:15" # ISO 8601 format
## "2011-7-8 13:14"
## "13:14" # today assumed
## "<{dtm}" # at or before the datetime
## "{dtm1} to {dtm2} # inclusive date range
$ hg help patterns # File name patterns
# Faves include: (Assuming you are in foo directory)
## path:ack/file.c # No pattern but from repo root
## *.c # Any name ending in ".c" in current dir (foo)
## **.c # Any name ending in ".c" in current dir (foo) and its subdirs
## bar/*.c # Any name ending in ".c" in foo/bar dir
## re:.*\.c$ # Perl/Python RegExp for any name ending in ".c" anywhere in repo

# Common global options:
# --time # Time how long a command takes to run
# -h --help # Display help on a command and exit
# -d --date [DATE] # See for the date(s) specified

$ hg add 
# Mark files to be added to the repository.

$ hg branch [-fC] [NAME]
# Set or show current branch name
# Common options:
# -f --force # Set branch name even if it shadows an existing or closed branch 

$ hg branches [-ac]
# List the named branches of the repository
# Common options:
# -a --active # Show only branches with unmerged heads
# -c --closed # Show normal and closed branches

$ hg clone [OPTION]... SOURCE [DEST]
# Copy an existing repository. 
# Common options:
# -U --noupdate # Clone an empty repository

$ hg commit 
# Save changes. 
# Aka ci
# Common options:
# -A # Mark new/missing files as added/removed before committing
# -m --message TEXT # Use text as commit message.
# --close-branch # Mark a branch as closed

$ hg copy. 
# Mark files as copied for the next commit
# Aka: cp

$ hg diff [OPTION]... ([-c REV] | [-r REV1 [-r REV2]]) [FILE]... 
# Show differences between revisions or  files

$ hg export
# Output the changset head and diffs as a patch for an effective clone via file

$ hg forget
# Forget the specified files on the next commit

$ he heads
# Show current repo heads or branch heads

$ hg icoming SOURCE 
# Show new changesets in source
# Aka: in
# in:pull :: diff:ci

$ hg identify 
# ID the working copy or specified revision
# Aka: id

$ hg import
# Import a set of patches, i.e. get a version.
# Aka patch.

$ hg log 
# See revision history of repository or file.
$ hg log -d -2 # See log within 2 days of today
$ hg log -l 5 # See last 5 items


$ hg merge
# Merge working directory with another revision.
# Common options:
# -P --preview # Review revisions to merge (no merge is done)

$ hg pull SOURCE 
# Pull changes from specified source
# Will pull in branches, so run update/merge as needed.
# Common options:
# -f --force # Force push

$ hg push DESTINATION 
# Push changes to specified destination
# As if destination were pulling from you
# Common options:
# -f --force # Force push

$ hg rename 
# Mark destination as copy of source; Mark source for deletion.
# Aka move, mv

$ hg resolve
# Various operations to help finish a merge
# Common options:
# -a --all # Select all unresolved files
# -l --list # List state of unresolved files

$ hg revert
# Restore individual files or directories to an earlier state
# If no revision, then revert to unmodified state since the last commit.
# Common options:
# -a --all # revert all changes when no arguments given
# -r --rev REV # revert to the specified revision
# -n --dry-run # do not perform actions, just print output

$ hg rollback
# Rollback to the previous state.
# Do only if you haven't done a subsequent ci, pull, push, import, or unbundle

$ hg serve
# Start a webserver to share the repository
# Common options:
# -p --port PORT # port to listen on (default: 8000)

$ hg status 
# See which files changed.
# Aka st
# Common options:
# -A --all # Show status of all files
# -m --modified # Show only modified files. Status: M
# -a --added # Show only added files. Status: A
# -r --removed # Show only removed files. Status: R
# -c --clean # Show only clean (no changes) files. Status: C
# -d --deleted # Show only missing (but tracked) files. Status: !
# -u --unknown # Show only not tracked files. Status: ?
# -i --ignored # Show only ignored files. Status: I
# -I --include # inlcude names matching the given patterns
# -X --exclude # exclude names matching the given patterns
$ hg st -X "**foo**"

$ hg tag
# Add 1+ tags for the current or given revision
# Common options:
# -f --force # Force tag to overwrite
# -l --local # Make tag local
# --remove
# -m --message TEXT 
# -d --date DATE

$ hg tags
# List repository tags

$ hg tip
# Show the tip revision.

$ hg update 
# Update the working dir to the specified changeset (or tip if not specified)
# Aka up, checkout, co.
# Common options:
# -C --clean # Discard uncommitted changes
# -c --check # Update if no uncommitted changes
# -r --rev REV # Revision

Revision Control