1   Introduction

A note on terminology -- version control systems are also known as revision control systems, source control systems, or source code management systems.

A note on Bazaar vs. Breezy -- Breezy is described as "a friendly fork of Bazaar". In this document, I will discuss Breezy. I believe that what I say will be true of and will cover Bazaar as well.

So, the commands we'll be using and learning are git, hg (for Mercurial), and brz for Breezy.

2   Information sources and references

Some information sources on VCS in general:

Information on specific VCS software:

3   Basics -- The simple stuff

3.1   Git

For introductory information on basic workflows, see the "Pro Git" book, by Scott Chacon and Ben Straub, and which is available online -- https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository

3.2   Mercurial

For instructions on basic workflows, see -- https://www.mercurial-scm.org/guide

3.3   Breezy

For instructions on how to do a typical workflow, see -- https://www.breezy-vcs.org/doc/en/tutorials/tutorial.html

4   Cloning and copying

The clone command in Git and Mercurial and the branch command in Breezy enable you to make a complete copy of a repository with all its latest commits and all its history.

One proviso is that the repository that results from this operation will not contain changes in the originating repository that have not been committed in the originating repository.

And, on Breezy at least, you can clone (create a branch) across the network with something like this:

brz branch sftp://dkuhlman@jackdaw:/home/dkuhlman/a1/VCS/Test01/Brz/brz1 brz2

For a list of other transports, see -- https://www.breezy-vcs.org/doc/en/_static/en/brz-en-quick-reference.pdf

You can also do a deep, recursive copy of a directory containing a repository, in which case you will also copy changes that have not been committed. For example, something like this (on Linux) will do that task:

$ cp --recursive repo1 repo2

5   Branches and branching

Git and Mercurial do branches differently from Breezy. In both Git and Mercurial, branches can be created within a repository; then you can switch from working on one branch rather than another with the git update <branch-name> or hg update <branch-name>.

5.1   Git

Here are some commands that you will likely use for creating and using branches in Git:

# Create new branch named "featureA".
$ git branch featureA
# Switch to using and working on files in branch featureA.
$ git switch featureA
# git commit -m "changes to featureA"
# Show names of existing branches.
$ git branch
# Switch back to branch "master", then merge changes committed in branch "featureA".
$ git switch master
# Merge changes in branch "featureA" into branch "master".
$ git merge featureA
# Delete branch "featureA".
$ git branch -d featureA

For more information, see "Branching and Merging" here -- https://git-scm.com/docs

5.2   Mercurial

Here are some commands that you will likely use for creating and using branches in Mercurial:

# Create new branch named "featureA".
$ hg branch featureA
# hg commit -m "changes to featureA"
# Show names of existing branches.
$ hg branches
# Switch back to branch "default", then merge changes committed in branch "featureA".
$ hg update master
# Merge changes in branch "featureA" into branch "default".
# Then commit them in branch default.
$ hg merge featureA
$ hg commit -m "Merge from featureA"
# Finish with branch "featureA".
# Then switch back to working on the "default" branch.
$ hg commit --close-branch -m "Finished with featureA"
$ hg update default

For more information, see -- https://www.mercurial-scm.org/guide#collaborative_development

5.3   Breezy

Branches are quite different in Breezy, where a branch is just a separate directory containing a copy of a repository. In fact, the command for creating a new branch that is a "clone" of an existing branch is:

$ brz branch old_repo new_repo

After creating that new branch, i.e. a new directory with a copy of the original, you change directory (cd) to the new repository's directory, make changes to files, commit, etc as you normally would.

And, when you want to merge those changes back into the original repository, you cd back to that directory and do a merge:

$ cd old_repo
$ hg merge ../new_repo

Here is a sequence of commands that does some of those things:

# Make a branch/clone of the original repo.
$ brz branch original featureA
# Switch to the new branch/directory.
$ cd featureA
# Change some files, then commit those changes.
$ brz commit -m "Changes in featureA"
# Switch back the the original repo,
# then merge changes from repo "featureA"
$ cd ../original
$ brz merge ../featureA
$ brz commit -m "Merged changes from branch featureA"
# If we are finished with the branch, delete it.
# *But*, becareful.  We can't get it back.
# Might want to archive it instead.
$ cd ..
# Safer -- archive with zip and permanently delete it:
$ zip -m -r featureAarchive.zip featureA
# Or -- archive with tar and xz, then permanently delete it:
$ tar -cJf featureAarchive.tar.xz featureA
$ rm -rf featureA

You can save disk space (especially if you have a large repository and are making many branches) by using a shared repository. For information about that, see -- https://www.breezy-vcs.org/doc/en/user-guide/branching_a_project.html#a-reminder-about-shared-repositories

6   Workflows, collaboration, etc

You can read about working as a team, collaboration, and workflows here: