<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Bazaar in five minutes — Bazaar v2.2.4 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '2.2.4',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="shortcut icon" href="../_static/bzr.ico"/>
<link rel="top" title="Bazaar v2.2.4 documentation" href="../index.html" />
<link rel="up" title="Tutorials" href="../tutorials/index.html" />
<link rel="next" title="Bazaar Tutorial" href="../tutorials/tutorial.html" />
<link rel="prev" title="Tutorials" href="../tutorials/index.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../tutorials/tutorial.html" title="Bazaar Tutorial"
accesskey="N">next</a></li>
<li class="right" >
<a href="../tutorials/index.html" title="Tutorials"
accesskey="P">previous</a> |</li>
<li><a href="http://bazaar.canonical.com/">
<img src="../_static/bzr icon 16.png" /> Home</a> | </li>
<a href="http://doc.bazaar.canonical.com/en/">Documentation</a> | </li>
<li><a href="../index.html">Table of Contents (2.2.4)</a> »</li>
<li><a href="../tutorials/index.html" accesskey="U">Tutorials</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="bazaar-in-five-minutes">
<h1>Bazaar in five minutes<a class="headerlink" href="#bazaar-in-five-minutes" title="Permalink to this headline">¶</a></h1>
<div class="section" id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>Bazaar is a distributed version control system that makes it easier for
people to work together on software projects.</p>
<p>Over the next five minutes, you’ll learn how to put your files under
version control, how to record changes to them, examine your work, publish
it and send your work for merger into a project’s trunk.</p>
<p>If you’d prefer a more detailed introduction, take a look at
<a class="reference internal" href="#learning-more">Learning More</a>.</p>
</div>
<div class="section" id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h2>
<p>This guide doesn’t describe how to install Bazaar but it’s usually very
easy. You can find installation instructions at:</p>
<ul class="simple">
<li><strong>GNU/Linux:</strong> Bazaar is probably in your GNU/Linux distribution already.</li>
<li><strong>Windows:</strong> <a class="reference external" href="http://wiki.bazaar.canonical.com/WindowsDownloads">installation instructions for Windows</a>.</li>
<li><strong>Mac OS X:</strong> <a class="reference external" href="http://wiki.bazaar.canonical.com/MacOSXBundle">installation instructions for Mac OS X</a>.</li>
</ul>
<p>For other platforms and to install from source code, see the <a class="reference external" href="http://wiki.bazaar.canonical.com/Download">Download</a>
and <a class="reference external" href="http://wiki.bazaar.canonical.com/InstallationFaq">Installation</a> pages.</p>
</div>
<div class="section" id="introducing-yourself">
<h2>Introducing yourself<a class="headerlink" href="#introducing-yourself" title="Permalink to this headline">¶</a></h2>
<p>Before you start working, it is good to tell Bazaar who you are. That
way your work is properly identified in revision logs.</p>
<p>Using your name and email address, instead of John Doe’s, type:</p>
<div class="highlight-python"><pre>$ bzr whoami "John Doe <john.doe@gmail.com>"</pre>
</div>
<p>Bazaar will now create or modify a configuration file, including your
name and email address.</p>
<p>Now, check that your name and email address are correctly registered:</p>
<div class="highlight-python"><pre>$ bzr whoami
John Doe <john.doe@gmail.com></pre>
</div>
</div>
<div class="section" id="putting-files-under-version-control">
<h2>Putting files under version control<a class="headerlink" href="#putting-files-under-version-control" title="Permalink to this headline">¶</a></h2>
<p>Let’s create a directory and some files to use with Bazaar:</p>
<div class="highlight-python"><pre>$ mkdir myproject
$ cd myproject
$ mkdir subdirectory
$ touch test1.txt test2.txt test3.txt subdirectory/test4.txt</pre>
</div>
<p><strong>Note for Windows users:</strong> use Windows Explorer to create your
directories, then right-click in those directories and select
<tt class="docutils literal"><span class="pre">New</span> <span class="pre">file</span></tt> to create your files.</p>
<p>Now get Bazaar to initialize itself in your project directory:</p>
<div class="highlight-python"><pre>$ bzr init</pre>
</div>
<p>If it looks like nothing happened, don’t worry. Bazaar has created a
<a class="reference external" href="http://wiki.bazaar.canonical.com/Branch">branch</a> where it will store your files and their revision histories.</p>
<p>The next step is to tell Bazaar which files you want to track. Running
<tt class="docutils literal"><span class="pre">bzr</span> <span class="pre">add</span></tt> will recursively add everything in the project:</p>
<div class="highlight-python"><pre>$ bzr add
added subdirectory
added test1.txt
added test2.txt
added test3.txt
added subdirectory/test4.txt</pre>
</div>
<p>Next, take a snapshot of your files by committing them to your branch. Add
a message to explain why you made the commit:</p>
<div class="highlight-python"><pre>$ bzr commit -m "Initial import"</pre>
</div>
<p>As Bazaar is a distributed version control system, it doesn’t need to
connect to a central server to make the commit. Instead, Bazaar stores your
branch and all its commits inside the directory you’re working with; look
for the <tt class="docutils literal"><span class="pre">.bzr</span></tt> sub-directory.</p>
</div>
<div class="section" id="making-changes-to-your-files">
<h2>Making changes to your files<a class="headerlink" href="#making-changes-to-your-files" title="Permalink to this headline">¶</a></h2>
<p>Let’s change a file and commit that change to your branch.</p>
<p>Edit <tt class="docutils literal"><span class="pre">test1.txt</span></tt> in your favourite editor, then check what have you done:</p>
<div class="highlight-python"><pre>$ bzr diff
=== modified file 'test1.txt'
--- test1.txt 2007-10-08 17:56:14 +0000
+++ test1.txt 2007-10-08 17:46:22 +0000
@@ -0,0 +1,1 @@
+test test test</pre>
</div>
<p>Commit your work to the Bazaar branch:</p>
<div class="highlight-python"><pre>$ bzr commit -m "Added first line of text"
Committed revision 2.</pre>
</div>
</div>
<div class="section" id="viewing-the-revision-log">
<h2>Viewing the revision log<a class="headerlink" href="#viewing-the-revision-log" title="Permalink to this headline">¶</a></h2>
<p>You can see the history of your branch by browsing its log:</p>
<div class="highlight-python"><pre>$ bzr log
------------------------------------------------------------
revno: 2
committer: John Doe <john.doe@gmail.com>
branch nick: myproject
timestamp: Mon 2007-10-08 17:56:14 +0000
message:
Added first line of text
------------------------------------------------------------
revno: 1
committer: John Doe <john.doe@gmail.com>
branch nick: myproject
timestamp: Mon 2006-10-08 17:46:22 +0000
message:
Initial import</pre>
</div>
</div>
<div class="section" id="publishing-your-branch-with-sftp">
<h2>Publishing your branch with sftp<a class="headerlink" href="#publishing-your-branch-with-sftp" title="Permalink to this headline">¶</a></h2>
<p>There are a couple of ways to publish your branch. If you already have
an SFTP server or are comfortable setting one up, you can publish your
branch to it.</p>
<p>Otherwise, skip to the next section to publish with <a class="reference external" href="https://launchpad.net/">Launchpad</a>, a free
hosting service for Bazaar.</p>
<p>Let’s assume you want to publish your branch at <tt class="docutils literal"><span class="pre">www.example.com/myproject</span></tt>:</p>
<div class="highlight-python"><pre>$ bzr push --create-prefix sftp://your.name@example.com/~/public_html/myproject
2 revision(s) pushed.</pre>
</div>
<p>Bazaar will create a <tt class="docutils literal"><span class="pre">myproject</span></tt> directory on the remote server and
push your branch to it.</p>
<p>Now anyone can create their own copy of your branch by typing:</p>
<div class="highlight-python"><pre>$ bzr branch http://www.example.com/myproject</pre>
</div>
<p><strong>Note:</strong> to use sftp, you may need to install <tt class="docutils literal"><span class="pre">paramiko</span></tt> and
<tt class="docutils literal"><span class="pre">pyCrypto</span></tt>. See <a class="reference external" href="http://wiki.bazaar.canonical.com/InstallationFaq">http://wiki.bazaar.canonical.com/InstallationFaq</a> for details.</p>
</div>
<div class="section" id="publishing-your-branch-with-launchpad">
<h2>Publishing your branch with Launchpad<a class="headerlink" href="#publishing-your-branch-with-launchpad" title="Permalink to this headline">¶</a></h2>
<p>Launchpad is a suite of development and hosting tools for free
software projects. You can use it to publish your branch.</p>
<p>If you don’t have a Launchpad account, follow the <a class="reference external" href="https://help.launchpad.net/CreatingYourLaunchpadAccount">account signup guide</a>
and <a class="reference external" href="https://launchpad.net/people/+me/+editsshkeys">register an SSH key</a> in your new Launchpad account.</p>
<p>Replacing <tt class="docutils literal"><span class="pre">john.doe</span></tt> with your own Launchpad username, type <a class="footnote-reference" href="#id3" id="id2">[1]</a>:</p>
<div class="highlight-python"><pre>$ bzr push lp:~john.doe/+junk/myproject</pre>
</div>
<table class="docutils footnote" frame="void" id="id3" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2">[1]</a></td><td>Use of the <tt class="docutils literal"><span class="pre">lp:</span></tt> URL scheme requires bzr 0.92 or later.</td></tr>
</tbody>
</table>
<p><strong>Note:</strong> <tt class="docutils literal"><span class="pre">+junk</span></tt> means that this branch isn’t associated with any particular
project in Launchpad.</p>
<p>Now, anyone can create their own copy of your branch by typing:</p>
<div class="highlight-python"><pre>$ bzr branch lp:~john.doe/+junk/myproject</pre>
</div>
<p>You can also see information about your branch, including its revision
history, at <a class="reference external" href="https://code.launchpad.net/people/+me/+junk/myproject">https://code.launchpad.net/people/+me/+junk/myproject</a></p>
</div>
<div class="section" id="creating-your-own-copy-of-another-branch">
<h2>Creating your own copy of another branch<a class="headerlink" href="#creating-your-own-copy-of-another-branch" title="Permalink to this headline">¶</a></h2>
<p>To work with someone else’s code, you can make your own copy of their
branch. Let’s take a real-world example, Bazaar’s GTK interface:</p>
<div class="highlight-python"><pre>$ bzr branch lp:~bzr/bzr-gtk/trunk bzr-gtk.john
Branched 292 revision(s).</pre>
</div>
<p>Bazaar will download all the files and complete revision history from the
bzr-gtk project’s trunk branch and create a copy called bzr-gtk.john.</p>
<p>Now, you have your own copy of the branch and can commit changes with
or without a net connection. You can share your branch at any time by
publishing it and, if the bzr-gtk team want to use your work, Bazaar
makes it easy for them to merge your branch back into their trunk branch.</p>
</div>
<div class="section" id="updating-your-branch-from-the-main-branch">
<h2>Updating your branch from the main branch<a class="headerlink" href="#updating-your-branch-from-the-main-branch" title="Permalink to this headline">¶</a></h2>
<p>While you commit changes to your branch, it’s likely that other people will
also continue to commit code to the parent branch.</p>
<p>To make sure your branch stays up to date, you should merge changes from
the parent into your personal branch:</p>
<div class="highlight-python"><pre>$ bzr merge
Merging from saved parent location: http://bazaar.launchpad.net/~bzr/bzr-gtk/trunk
All changes applied successfully.</pre>
</div>
<p>Check what has changed:</p>
<div class="highlight-python"><pre>$ bzr diff</pre>
</div>
<p>If you’re happy with the changes, you can commit them to your personal
branch:</p>
<div class="highlight-python"><pre>$ bzr commit -m "Merge from main branch"
Committed revision 295.</pre>
</div>
</div>
<div class="section" id="merging-your-work-into-the-parent-branch">
<h2>Merging your work into the parent branch<a class="headerlink" href="#merging-your-work-into-the-parent-branch" title="Permalink to this headline">¶</a></h2>
<p>After you’ve worked on your personal branch of bzr-gtk, you may want to
send your changes back upstream to the project. The easiest way is to
use a merge directive.</p>
<p>A merge directive is a machine-readable request to perform a
particular merge. It usually contains a patch preview of the merge
and either contains the necessary revisions, or provides a branch
where they can be found.</p>
<p>Replacing <tt class="docutils literal"><span class="pre">mycode.patch</span></tt>, create your merge directive:</p>
<div class="highlight-python"><pre>$ bzr send -o mycode.patch
Using saved parent location: http://bazaar.launchpad.net/~bzr/bzr-gtk/trunk</pre>
</div>
<p>You can now email the merge directive to the bzr-gtk project who, if
they choose, can use it merge your work back into the parent branch.</p>
</div>
<div class="section" id="learning-more">
<h2>Learning more<a class="headerlink" href="#learning-more" title="Permalink to this headline">¶</a></h2>
<p>You can find out more about Bazaar in the
<a class="reference external" href="../user-guide/index.html">Bazaar User Guide</a>.</p>
<p>To learn about Bazaar on the command-line:</p>
<div class="highlight-python"><pre>$ bzr help</pre>
</div>
<p>To learn about Bazaar commands:</p>
<div class="highlight-python"><pre>$ bzr help commands</pre>
</div>
<p>To learn about the ‘’foo’’ topic or command:</p>
<div class="highlight-python"><pre>$ bzr help foo</pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Bazaar in five minutes</a><ul>
<li><a class="reference internal" href="#introduction">Introduction</a></li>
<li><a class="reference internal" href="#installation">Installation</a></li>
<li><a class="reference internal" href="#introducing-yourself">Introducing yourself</a></li>
<li><a class="reference internal" href="#putting-files-under-version-control">Putting files under version control</a></li>
<li><a class="reference internal" href="#making-changes-to-your-files">Making changes to your files</a></li>
<li><a class="reference internal" href="#viewing-the-revision-log">Viewing the revision log</a></li>
<li><a class="reference internal" href="#publishing-your-branch-with-sftp">Publishing your branch with sftp</a></li>
<li><a class="reference internal" href="#publishing-your-branch-with-launchpad">Publishing your branch with Launchpad</a></li>
<li><a class="reference internal" href="#creating-your-own-copy-of-another-branch">Creating your own copy of another branch</a></li>
<li><a class="reference internal" href="#updating-your-branch-from-the-main-branch">Updating your branch from the main branch</a></li>
<li><a class="reference internal" href="#merging-your-work-into-the-parent-branch">Merging your work into the parent branch</a></li>
<li><a class="reference internal" href="#learning-more">Learning more</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="../tutorials/index.html"
title="previous chapter">Tutorials</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="../tutorials/tutorial.html"
title="next chapter">Bazaar Tutorial</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/mini-tutorial/index.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../tutorials/tutorial.html" title="Bazaar Tutorial"
>next</a></li>
<li class="right" >
<a href="../tutorials/index.html" title="Tutorials"
>previous</a> |</li>
<li><a href="http://bazaar.canonical.com/">
<img src="../_static/bzr icon 16.png" /> Home</a> | </li>
<a href="http://doc.bazaar.canonical.com/en/">Documentation</a> | </li>
<li><a href="../index.html">Table of Contents (2.2.4)</a> »</li>
<li><a href="../tutorials/index.html" >Tutorials</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2009, Canonical Ltd.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>
</html>
