Rev 2915: (mrevell) Bazaar in 5 minutes doc in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Thu Oct 18 04:28:29 BST 2007
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 2915
revision-id: pqm at pqm.ubuntu.com-20071018032827-gg3yjbq11ex02168
parent: pqm at pqm.ubuntu.com-20071017083250-zstfljmmitbo4e1j
parent: mbp at sourcefrog.net-20071018024824-iu04uiofadqvusol
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Thu 2007-10-18 04:28:27 +0100
message:
(mrevell) Bazaar in 5 minutes doc
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
doc/en/mini-tutorial/index.txt index.txt-20070813141352-2u64ooqzo0or4hss-2
doc/index.txt index.txt-20070813101924-07gd9i9d2jt124bf-1
------------------------------------------------------------
revno: 2914.1.2
merged: mbp at sourcefrog.net-20071018024824-iu04uiofadqvusol
parent: mbp at sourcefrog.net-20071018024639-odra1qeva6s9l9se
committer: Martin Pool <mbp at sourcefrog.net>
branch nick: doc
timestamp: Thu 2007-10-18 12:48:24 +1000
message:
Mention bzr5m in news
------------------------------------------------------------
revno: 2914.1.1
merged: mbp at sourcefrog.net-20071018024639-odra1qeva6s9l9se
parent: pqm at pqm.ubuntu.com-20071017083250-zstfljmmitbo4e1j
parent: matthew.revell at canonical.com-20071016140509-r1hhoi7cumdve07l
committer: Martin Pool <mbp at sourcefrog.net>
branch nick: doc
timestamp: Thu 2007-10-18 12:46:39 +1000
message:
Merge updated 'Bazaar in 5 minutes' from Matthew Revell
------------------------------------------------------------
revno: 2866.2.10
merged: matthew.revell at canonical.com-20071016140509-r1hhoi7cumdve07l
parent: matthew.revell at canonical.com-20071016140149-l23wqk5kri65hjrl
committer: Matthew Revell <matthew.revell at canonical.com>
branch nick: trunk
timestamp: Tue 2007-10-16 15:05:09 +0100
message:
Fixed typos.
------------------------------------------------------------
revno: 2866.2.9
merged: matthew.revell at canonical.com-20071016140149-l23wqk5kri65hjrl
parent: matthew.revell at canonical.com-20071016132510-eczgugszxd23u8eq
committer: Matthew Revell <matthew.revell at canonical.com>
branch nick: trunk
timestamp: Tue 2007-10-16 15:01:49 +0100
message:
Corrected 'bundle' to be 'merge directive'
------------------------------------------------------------
revno: 2866.2.8
merged: matthew.revell at canonical.com-20071016132510-eczgugszxd23u8eq
parent: matthew.revell at canonical.com-20071016110630-0ij1zujgy2ylvchw
committer: Matthew Revell <matthew.revell at canonical.com>
branch nick: trunk
timestamp: Tue 2007-10-16 14:25:10 +0100
message:
Changed 'bundle' to 'merge directive' on Aaron's suggestion, using his description of a merge directive
------------------------------------------------------------
revno: 2866.2.7
merged: matthew.revell at canonical.com-20071016110630-0ij1zujgy2ylvchw
parent: matthew.revell at canonical.com-20071010173538-qw5tbsv2zhmelexl
committer: Matthew Revell <matthew.revell at canonical.com>
branch nick: trunk
timestamp: Tue 2007-10-16 12:06:30 +0100
message:
Ian, John AM, Poolie, John G comments acted on. Corrected bzr send section, used 'parent' instead of 'main' branch, included two publishing sections - one for LP and one for sftp.
------------------------------------------------------------
revno: 2866.2.6
merged: matthew.revell at canonical.com-20071010173538-qw5tbsv2zhmelexl
parent: matthew.revell at canonical.com-20071010171609-q6tbzlifjfok71x8
committer: Matthew Revell <matthew.revell at canonical.com>
branch nick: trunk
timestamp: Wed 2007-10-10 18:35:38 +0100
message:
Provisional update if 'learning more' section
------------------------------------------------------------
revno: 2866.2.5
merged: matthew.revell at canonical.com-20071010171609-q6tbzlifjfok71x8
parent: matthew.revell at canonical.com-20071008204245-pq7hezwgs6tmqed4
parent: pqm at pqm.ubuntu.com-20071008081200-04a0byt5lo5tyft9
committer: Matthew Revell <matthew.revell at canonical.com>
branch nick: trunk
timestamp: Wed 2007-10-10 18:16:09 +0100
message:
Updated with Launchpad push and poolie, John G and Jam changes
------------------------------------------------------------
revno: 2866.2.4
merged: matthew.revell at canonical.com-20071008204245-pq7hezwgs6tmqed4
parent: matthew.revell at canonical.com-20071003163602-od4zb77omj4hdzg5
committer: Matthew Revell <matthew.revell at canonical.com>
branch nick: trunk
timestamp: Mon 2007-10-08 21:42:45 +0100
message:
mini-tutorial revision 3
------------------------------------------------------------
revno: 2866.2.3
merged: matthew.revell at canonical.com-20071003163602-od4zb77omj4hdzg5
parent: matthew.revell at canonical.com-20071003163505-n5l5z73bshd6p8ie
parent: pqm at pqm.ubuntu.com-20070928041435-uls0r9txks111272
committer: Matthew Revell <matthew.revell at canonical.com>
branch nick: trunk
timestamp: Wed 2007-10-03 17:36:02 +0100
message:
merge with trunk
------------------------------------------------------------
revno: 2866.2.2
merged: matthew.revell at canonical.com-20071003163505-n5l5z73bshd6p8ie
parent: matthew.revell at canonical.com-20070928153527-cd373nqctylecy5x
committer: Matthew Revell <matthew.revell at canonical.com>
branch nick: trunk
timestamp: Wed 2007-10-03 17:35:05 +0100
message:
second revision of new Bazaar in Five Minutes
------------------------------------------------------------
revno: 2866.2.1
merged: matthew.revell at canonical.com-20070928153527-cd373nqctylecy5x
parent: pqm at pqm.ubuntu.com-20070925212801-8p7l0qlplb0t7h2u
committer: Matthew Revell <matthew.revell at canonical.com>
branch nick: trunk
timestamp: Fri 2007-09-28 16:35:27 +0100
message:
Rewrite of mini-tutorial as 'Bazaar in 5 minutes'
=== modified file 'NEWS'
--- a/NEWS 2007-10-16 09:49:18 +0000
+++ b/NEWS 2007-10-18 02:48:24 +0000
@@ -78,6 +78,11 @@
* Show encodings, locale and list of plugins in the traceback message.
(Martin Pool, #63894)
+
+ DOCUMENTATION:
+
+ * New *Bazaar in Five Minutes* guide. (Matthew Revell)
+
BUG FIXES:
* ``bzr+ssh://`` and ``sftp://`` URLs that do not specify ports explicitly
=== modified file 'doc/en/mini-tutorial/index.txt'
--- a/doc/en/mini-tutorial/index.txt 2007-08-13 14:16:53 +0000
+++ b/doc/en/mini-tutorial/index.txt 2007-10-16 14:05:09 +0000
@@ -1,189 +1,278 @@
-====================
-Bazaar Mini Tutorial
-====================
+===================
+Bazaar in five minutes
+===================
.. contents::
Introduction
============
-This is a very brief 5-minute tutorial, covering only what a first time user
-needs to start a project or start contributing to a project using Bazaar.
-For a more detailed look, see `Learning More`_.
+Bazaar is a distributed version control system that makes it easier for
+people to work together on software projects.
+
+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.
+
+If you'd prefer a more detailed introduction, take a look at
+`Learning More`_.
Installation
============
-See http://bazaar-vcs.org/Download. Bazaar is probably in your GNU/Linux
-distribution already. If not, it's trivial to install on any platform that
-runs Python 2.4, including Windows. Installation should take at most a few
-minutes.
-
-
-Introducing Yourself
+This guide doesn't describe how to install Bazaar but it's usually very
+easy. You can find installation instructions at:
+
+- **GNU/Linux:** Bazaar is probably in your GNU/Linux distribution already.
+- **Windows:** `installation instructions`_.
+- **Mac OS X:** `install using MacPorts`_.
+
+For other platforms and to install from source code, see the Downloads_
+and Installation_ pages.
+
+.. _installation instructions: http://bazaar-vcs.org/WindowsDownloads
+.. _install using MacPorts: http://bazaar-vcs.org/MacPorts
+.. _Downloads: http://bazaar-vcs.org/Download
+.. _Installation: http://bazaar-vcs.org/InstallationFAQ
+
+
+Introducing yourself
====================
-You want Bazaar to correctly identify you in revision logs. Using your name
-and email instead of Joe Doe's, type::
-
- $ bzr whoami "Joe Doe <joe.doe at gmail.com>"
-
-Now try::
+Before you start working, it is good to tell Bazaar who you are. That
+way your work is properly identified in revision logs.
+
+Using your name and email address, instead of John Doe's, type::
+
+ $ bzr whoami "John Doe <john.doe at gmail.com>"
+
+Bazaar will now create or modify a configuration file, including your
+name and email address.
+
+Now, check that your name and email address are correctly registered::
$ bzr whoami
- Joe Doe <joe.doe at gmail.com>
-
-
-Putting Existing Files Under Version Control
-============================================
-
-It is very easy to put an existing set of files under version control using
-Bazaar::
-
- $ cd my-project
- $ bzr init .
- $ bzr add
+ John Doe <john.doe at gmail.com>
+
+
+Putting files under version control
+===================================
+
+Let's create a directory and some files to use with Bazaar::
+
+ $ mkdir myproject
+ $ cd myproject
+ $ mkdir subdirectory
+ $ touch test1.txt test2.txt test3.txt subdirectory/test4.txt
+
+**Note for Windows users:** use Windows Explorer to create your
+directories, then right-click in those directories and select
+``New file`` to create your files.
+
+Now get Bazaar to initalize itself in your project directory::
+
+ $ bzr init
+
+If it looks like nothing happened, don't worry. Bazaar has created a
+branch_ where it will store your files and their revision histories.
+
+.. _branch: http://bazaar-vcs.org/Branch
+
+The next step is to tell Bazaar which files you want to track. Running
+``bzr add`` will recursively add everything in the project::
+
+ $ bzr add
+ added subdirectory
+ added test1.txt
+ added test2.txt
+ added test3.txt
+ added subdirectory/test4.txt
+
+Next, take a snapshot of your files by committing them to your branch. Add
+a message to explain why you made the commit::
+
$ bzr commit -m "Initial import"
-
-You can now make changes, track them, publish your branch and so on as
-explained below.
-
-
-Creating A Personal Branch
-==========================
-
-Rather than starting a new project, you may wish to work on an existing
-project either you or someone else has published.
-
-Create a branch of an existing project::
-
- $ bzr branch http://example.com/code/foobar.dev foobar.joe
- Branched 1 revision(s).
-
-Note that after you create a personal branch, you don't need web access to
-commit changes.
-
-
-Making Changes
-==============
-
-Edit a file::
-
- $ cd foobar.joe
- $ hack...
-
-Check what have you done::
-
- $ bzr diff
- === modified file 'foo.c'
- --- foo.c
- +++ foo.c
- @@ -30,6 +30,7 @@
-
- #include "foo.h"
-
- +
- static PyObject *
- _pyfribidi_log2vis (PyObject * self, PyObject * args, PyObject * kw)
- {
-
-Commit your hard work::
-
- $ bzr commit -m 'added some whitespace'
+
+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 ``.bzr`` sub-directory.
+
+
+Making changes to your files
+============================
+
+Let's change a file and commit those changes to your branch.
+
+Edit ``test1.txt`` in your favourite editor, then check what have you done::
+
+ $ 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
+
+Commit your work to the Bazaar branch::
+
+ $ bzr commit -m 'Added first line of text'
Committed revision 2.
-Viewing the Revision Log
+Viewing the revision log
========================
-Browse the history of the branch::
+You can see the history of your branch by browsing its log::
$ bzr log
------------------------------------------------------------
revno: 2
- committer: Joe Doe <joe.doe at gmail.com>
- branch nick: foobar.joe
- timestamp: Mon 2006-02-06 01:33:35 +0200
+ committer: John Doe <john.doe at gmail.com>
+ branch nick: myproject
+ timestamp: Mon 2007-10-08 17:56:14 +0000
message:
- added some whitespace
+ Added first line of text
------------------------------------------------------------
revno: 1
- committer: James Hacker <jmh at example.com>
- branch nick: foobar.dev
- timestamp: Mon 2006-02-06 01:06:11 +0200
+ committer: John Doe <john.doe at gmail.com>
+ branch nick: myproject
+ timestamp: Mon 2006-10-08 17:46:22 +0000
message:
- initial revision
-
-
-Updating Your Branch from the Main Branch
+ Initial import
+
+
+Publishing your branch with sftp
+================================
+
+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.
+
+Otherwise, skip to the next section to publish with Launchpad_, a free
+hosting service for Bazaar.
+
+.. _Launchpad: https://launchpad.net/
+
+Let's assume you want to publish your branch at ``www.example.com/myproject``::
+
+ $ bzr push --create-prefix sftp://your.name@example.com/~/public_html/myproject
+ 2 revision(s) pushed.
+
+Bazaar will create a ``myproject`` directory on the remote server and
+push your branch to it.
+
+**Note:** to use sftp, you may need to install ``paramiko`` and
+``pyCrypto``. See http://bazaar-vcs.org/InstallationFaq for details.
+
+Now anyone can create their own copy of your branch by typing::
+
+ $ bzr branch http://www.example.com/myproject
+
+
+Publishing your branch with Launchpad
+=====================================
+
+Launchpad is a suite of development and hosting tools for free
+software projects. You can use it to publish your branch.
+
+If you don't have a Launchpad account, follow the `account signup guide`_
+and `register an SSH key`_ in your new Launchpad account.
+
+.. _account signup guide: https://help.launchpad.net/CreatingYourLaunchpadAccount
+.. _register an SSH key: https://launchpad.net/people/+me/+editsshkeys
+
+Replacing ``john.doe`` with your own Launchpad username, type::
+
+ $ bzr push bzr+ssh://john.doe@bazaar.launchpad.net/~john.doe/+junk/myproject
+
+**Note:** ``+junk`` means that this branch isn't associated with any particular
+project in Launchpad.
+
+Now, anyone can create their own copy of your branch by typing::
+
+ $ bzr branch http://bazaar.launchpad.net/~john.doe/+junk/myproject
+
+You can also see information about your branch, including its revision
+history, at https://code.launchpad.net/people/+me/+junk/myproject
+
+
+Creating your own copy of another branch
+========================================
+
+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::
+
+ $ bzr branch http://bazaar.launchpad.net/~bzr/bzr-gtk/trunk bzr-gtk.john
+ Branched 292 revision(s).
+
+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.
+
+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.
+
+
+Updating your branch from the main branch
=========================================
-While you work hard on your branch, others may have committed new code to the
-main branch. From time to time, you want to merge changes from the main
-branch into your branch::
+While you commit changes to your branch, it's likely that other people will
+also continue to commit code to the parent branch.
+
+To make sure your branch stays up to date, you should merge changes from
+the parent into your personal branch::
$ bzr merge
- Using saved location: http://example.com/code/foobar.dev
+ Using saved location: http://bazaar.launchpad.net/~bzr/bzr-gtk/trunk
All changes applied successfully.
-What was changed locally by merging the main branch?
-
-::
+Check what has changed::
$ bzr diff
- === modified file 'pyfribidi.c'
- --- pyfribidi.c
- +++ pyfribidi.c
- @@ -236,6 +236,7 @@
- PyMem_Del (logical);
- PyMem_Del (visual);
-
- + /* evil hack! */
- return result;
- }
-
-Commit the changes from the main branch::
-
- $ bzr commit -m 'merge from main branch'
- Committed revision 6.
-
-Note that you may occasionally need to resolve conflicts or make other minor
-changes (so tests pass say) before committing. For these reasons, merge does
-not implicitly commit.
-
-
-Publishing Your Branch
-======================
-
-You can simply use rsync to copy your branch to a web server, but using
-``bzr push`` is the easiest way. Let's assume you want to publish your
-branch in jod.example.com/foobar.joe and you have sftp access to the server::
-
- $ bzr push sftp://jod@jod.example.com/public_html/foobar.joe/
- 2 revision(s) pushed.
-
-Note that to use sftp, your may need to install ''paramiko'' and ''pyCrypto''.
-See http://bazaar-vcs.org/InstallationFaq for details.
-
-Now anyone can get your branch with (try it yourself!)::
-
- bzr branch http://jod.example.com/foobar.joe/
-
-
-Learning More
+
+If you're happy with the changes, you can commit them to your personal
+branch::
+
+ $ bzr commit -m 'Merge from main branch'
+ Committed revision 295.
+
+
+Merging your work into the parent branch
+========================================
+
+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.
+
+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.
+
+Replacing ``mycode.patch``, create your merge directive::
+
+ $ bzr send -o mycode.patch
+ Using saved location: http://bazaar.launchpad.net/~bzr/bzr-gtk/trunk
+
+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.
+
+
+Learning more
=============
-To learn about bzr topics::
+You can find out more about Bazaar in the `Bazaar user guide <../../index.html>`_.
+
+To learn about Bazaar on the command-line::
$ bzr help
-To learn about bzr commands::
+To learn about Bazaar commands::
$ bzr help commands
To learn about the ''foo'' topic or command::
$ bzr help foo
-
-Alternatively, browse the `Bazaar Documentation <../../index.html>`_.
=== modified file 'doc/index.txt'
--- a/doc/index.txt 2007-08-13 14:33:10 +0000
+++ b/doc/index.txt 2007-10-16 11:06:30 +0000
@@ -8,7 +8,7 @@
Core Documentation
==================
-* `Mini Tutorial <en/mini-tutorial/index.html>`_
+* `Bazaar in five minutes <en/mini-tutorial/index.html>`_
* `Quick Start Summary <en/quick-reference/quick-start-summary.svg>`_
More information about the bazaar-commits
mailing list