/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to doc/en/mini-tutorial/index.txt

  • Committer: Robert Collins
  • Date: 2010-05-06 23:41:35 UTC
  • mto: This revision was merged to the branch mainline in revision 5223.
  • Revision ID: robertc@robertcollins.net-20100506234135-yivbzczw1sejxnxc
Lock methods on ``Tree``, ``Branch`` and ``Repository`` are now
expected to return an object which can be used to unlock them. This reduces
duplicate code when using cleanups. The previous 'tokens's returned by
``Branch.lock_write`` and ``Repository.lock_write`` are now attributes
on the result of the lock_write. ``repository.RepositoryWriteLockResult``
and ``branch.BranchWriteLockResult`` document this. (Robert Collins)

``log._get_info_for_log_files`` now takes an add_cleanup callable.
(Robert Collins)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/mini-tutorial/index.txt
1
1
======================
2
 
Breezy in five minutes
 
2
Bazaar in five minutes
3
3
======================
4
4
 
5
5
Introduction
6
6
============
7
7
 
8
 
Breezy is a distributed version control system that makes it easier for
 
8
Bazaar is a distributed version control system that makes it easier for
9
9
people to work together on software projects.
10
10
 
11
11
Over the next five minutes, you'll learn how to put your files under
12
12
version control, how to record changes to them, examine your work, publish
13
13
it and send your work for merger into a project's trunk.
14
14
 
 
15
If you'd prefer a more detailed introduction, take a look at
 
16
`Learning More`_.
 
17
 
15
18
 
16
19
Installation
17
20
============
18
21
 
19
 
This guide doesn't describe how to install Breezy but it's usually very
 
22
This guide doesn't describe how to install Bazaar but it's usually very
20
23
easy. You can find installation instructions at:
21
24
 
22
 
- **GNU/Linux:** Breezy is probably in your GNU/Linux distribution already.
 
25
- **GNU/Linux:** Bazaar is probably in your GNU/Linux distribution already.
23
26
- **Windows:** `installation instructions for Windows`_.
24
27
- **Mac OS X:** `installation instructions for Mac OS X`_.
25
28
 
26
29
For other platforms and to install from source code, see the Download_
27
30
and Installation_ pages.
28
31
 
29
 
.. _installation instructions for Windows: http://wiki.bazaar.canonical.com/WindowsDownloads
30
 
.. _installation instructions for Mac OS X: http://wiki.bazaar.canonical.com/MacOSXBundle
31
 
.. _Download: http://wiki.bazaar.canonical.com/Download
32
 
.. _Installation: http://wiki.bazaar.canonical.com/InstallationFaq
 
32
.. _installation instructions for Windows: http://bazaar-vcs.org/WindowsDownloads
 
33
.. _installation instructions for Mac OS X: http://bazaar-vcs.org/MacOSXBundle
 
34
.. _Download: http://bazaar-vcs.org/Download
 
35
.. _Installation: http://bazaar-vcs.org/InstallationFaq
33
36
 
34
37
 
35
38
Introducing yourself
36
39
====================
37
40
 
38
 
Breezy records changes to source code, and it records who made the change.
39
 
The person is identified by their name and email address.  (If you're
40
 
concerned about spam, you don't need to use a real address that you
41
 
actually read, but the convention is that it looks like an email address.)
42
 
 
43
 
Before you start working, let's tell Breezy who you are.  Using your name
44
 
and email address, instead of John Doe's, type::
45
 
 
46
 
  $ brz whoami "John Doe <john.doe@gmail.com>"
47
 
 
48
 
You can check what identity is stored in Breezy's configuration::
49
 
 
50
 
  $ brz whoami
 
41
Before you start working, it is good to tell Bazaar who you are. That
 
42
way your work is properly identified in revision logs.
 
43
 
 
44
Using your name and email address, instead of John Doe's, type::
 
45
 
 
46
  $ bzr whoami "John Doe <john.doe@gmail.com>"
 
47
 
 
48
Bazaar will now create or modify a configuration file, including your
 
49
name and email address.
 
50
 
 
51
Now, check that your name and email address are correctly registered::
 
52
 
 
53
  $ bzr whoami
51
54
  John Doe <john.doe@gmail.com>
52
55
 
53
56
 
54
 
Starting a new project
55
 
======================
56
 
 
57
 
Let's suppose we want to store a new project under Breezy.  First, we'll
58
 
make a *repository directory* to hold all our work related to this
59
 
project, where developers can create branches to test development of
60
 
specific features or, more generally, modifications to the working file
61
 
set.  
62
 
 
63
 
After creating the repository, change to that directory, and create the
64
 
project's main trunk branch.
65
 
 
66
 
::
67
 
 
68
 
  $ brz init-shared-repo sample
69
 
  Shared repository with trees (format: 2a)
70
 
  Location:
71
 
    shared repository: sample
72
 
  $ brz init sample/trunk
73
 
  Created a repository tree (format: 2a)                                         
74
 
  Using shared repository: /home/john/sample/
75
 
 
76
 
 
77
 
Adding files
78
 
============
79
 
 
80
 
Now that we have the trunk, we need to move to that directory and
81
 
create some example files for the first version of that project.  Create
82
 
a file ``test1.txt`` using a text editor (like emacs, nano, or notepad),
83
 
and save it.  Then we'll "add" the file, which tells brz we want it to
84
 
track changes::
85
 
 
86
 
  $ cd sample/trunk
87
 
  # create the file test1.txt now
88
 
  $ brz add test1.txt
89
 
  adding test1.txt
90
 
 
91
 
and then commit, which saves a snapshot of all versioned files::
92
 
 
93
 
  $ brz commit -m "Added first line of text"
94
 
  added test1.txt
95
 
  Committed revision 1.
 
57
Putting files under version control
 
58
===================================
 
59
 
 
60
Let's create a directory and some files to use with Bazaar::
 
61
 
 
62
 $ mkdir myproject
 
63
 $ cd myproject
 
64
 $ mkdir subdirectory
 
65
 $ touch test1.txt test2.txt test3.txt subdirectory/test4.txt
 
66
 
 
67
**Note for Windows users:** use Windows Explorer to create your
 
68
directories, then right-click in those directories and select
 
69
``New file`` to create your files.
 
70
 
 
71
Now get Bazaar to initialize itself in your project directory::
 
72
 
 
73
  $ bzr init
 
74
 
 
75
If it looks like nothing happened, don't worry. Bazaar has created a
 
76
branch_ where it will store your files and their revision histories.
 
77
 
 
78
.. _branch: http://bazaar-vcs.org/Branch
 
79
 
 
80
The next step is to tell Bazaar which files you want to track. Running
 
81
``bzr add`` will recursively add everything in the project::
 
82
 
 
83
 $ bzr add
 
84
 added subdirectory
 
85
 added test1.txt
 
86
 added test2.txt
 
87
 added test3.txt
 
88
 added subdirectory/test4.txt
 
89
 
 
90
Next, take a snapshot of your files by committing them to your branch. Add
 
91
a message to explain why you made the commit::
 
92
 
 
93
  $ bzr commit -m "Initial import"
 
94
 
 
95
As Bazaar is a distributed version control system, it doesn't need to
 
96
connect to a central server to make the commit. Instead, Bazaar stores your
 
97
branch and all its commits inside the directory you're working with; look
 
98
for the ``.bzr`` sub-directory.
96
99
 
97
100
 
98
101
Making changes to your files
99
102
============================
100
103
 
101
 
 
102
104
Let's change a file and commit that change to your branch.
103
105
 
104
 
Edit ``test1.txt`` in your favourite editor, then use ``brz add`` to tell brz
105
 
to track changes to this file ::
106
 
 
107
 
  $ echo test test test > test1.txt 
108
 
  $ brz add test1.txt
109
 
  adding test1.txt
110
 
 
111
 
`brz diff` shows the changes between the last revision in this branch, and your
112
 
current tree (or, with the ``-r`` option, between any two trees). ::
113
 
 
114
 
 $ brz diff
 
106
Edit ``test1.txt`` in your favourite editor, then check what have you done::
 
107
 
 
108
 $ bzr diff
115
109
 === modified file 'test1.txt'
116
110
 --- test1.txt   2007-10-08 17:56:14 +0000
117
111
 +++ test1.txt   2007-10-08 17:46:22 +0000
118
112
 @@ -0,0 +1,1 @@
119
113
 +test test test
120
114
 
121
 
Commit your work to the Breezy branch::
122
 
 
123
 
  $ brz commit -m "Added first line of text"
124
 
  Committing to: /home/john/sample/trunk/                             
125
 
  added test1.txt
126
 
  Committed revision 1.
 
115
Commit your work to the Bazaar branch::
 
116
 
 
117
  $ bzr commit -m "Added first line of text"
 
118
  Committed revision 2.
 
119
 
127
120
 
128
121
Viewing the revision log
129
122
========================
130
123
 
131
124
You can see the history of your branch by browsing its log::
132
125
 
133
 
  $ brz log
 
126
  $ bzr log
 
127
  ------------------------------------------------------------
 
128
  revno: 2
 
129
  committer: John Doe <john.doe@gmail.com>
 
130
  branch nick: myproject
 
131
  timestamp: Mon 2007-10-08 17:56:14 +0000
 
132
  message:
 
133
    Added first line of text
 
134
  ------------------------------------------------------------
134
135
  revno: 1
135
136
  committer: John Doe <john.doe@gmail.com>
136
 
  branch nick: trunk
 
137
  branch nick: myproject
137
138
  timestamp: Mon 2006-10-08 17:46:22 +0000
138
139
  message:
139
140
    Initial import
140
141
 
141
142
 
142
 
Publishing your branch on Launchpad
143
 
===================================
144
 
 
145
 
Launchpad is a suite of development and hosting tools for
146
 
software projects. You can use it to publish your branch.  (You can 
147
 
also publish branches onto your own server or other hosting services.)
148
 
 
149
 
The steps to publishing branches on Launchpad are:
150
 
 
151
 
1. Create a Launchpad account: visit the `Launchpad login page`_ and choose to create a new account.
152
 
    
153
 
.. _Launchpad login page: https://launchpad.net/+login
154
 
    
155
 
2. Breezy uses the SSH encryption and authentication protocol to connect
156
 
   to Launchpad.  You need to first `create an SSH key`_ on your own computer,
157
 
   by running the command::
158
 
    
159
 
       $ ssh-keygen
160
 
 
161
 
.. _create an SSH key: https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair    
162
 
       
163
 
3. `Upload your SSH public key to Launchpad`_.
164
 
 
165
 
.. _Upload your SSH public key to Launchpad: https://launchpad.net/~/+editsshkeys
166
 
    
167
 
4. `Make a team for your project`_.  Even if you're starting as the only
168
 
   developer on this project, creating a new one now will let you more
169
 
   easily add other people later.
170
 
 
171
 
.. _Make a team for your project: https://help.launchpad.net/Teams/CreatingAndRunning
172
 
      
173
 
5. `Create a project`_.
174
 
  
175
 
.. _Create a project: https://help.launchpad.net/Projects/Registering
176
 
 
177
 
6. Tell Breezy your Launchpad account name.  If your account is john.doe, type ::
178
 
  
179
 
      $ brz launchpad-login john.doe
180
 
 
181
 
7. `Push the branch for your project`_.  Once you've committed your changes 
182
 
   locally, you can publish them as the trunk of your new project by saying
183
 
    
184
 
       $ brz push lp:~sample-developers/sample/trunk
185
 
       
186
 
   (Of course, using the team and project names you just chose.)
187
 
 
188
 
.. _Push the branch for your project: https://help.launchpad.net/Code/UploadingABranch
 
143
Publishing your branch with sftp
 
144
================================
 
145
 
 
146
There are a couple of ways to publish your branch. If you already have
 
147
an SFTP server or are comfortable setting one up, you can publish your
 
148
branch to it.
 
149
 
 
150
Otherwise, skip to the next section to publish with Launchpad_, a free
 
151
hosting service for Bazaar.
 
152
 
 
153
.. _Launchpad: https://launchpad.net/
 
154
 
 
155
Let's assume you want to publish your branch at ``www.example.com/myproject``::
 
156
 
 
157
 $ bzr push --create-prefix sftp://your.name@example.com/~/public_html/myproject
 
158
 2 revision(s) pushed.
 
159
 
 
160
Bazaar will create a ``myproject`` directory on the remote server and
 
161
push your branch to it.
 
162
 
 
163
Now anyone can create their own copy of your branch by typing::
 
164
 
 
165
 $ bzr branch http://www.example.com/myproject
 
166
 
 
167
**Note:** to use sftp, you may need to install ``paramiko`` and
 
168
``pyCrypto``. See http://bazaar-vcs.org/InstallationFaq for details.
 
169
 
 
170
 
 
171
Publishing your branch with Launchpad
 
172
=====================================
 
173
 
 
174
Launchpad is a suite of development and hosting tools for free
 
175
software projects. You can use it to publish your branch.
 
176
 
 
177
If you don't have a Launchpad account, follow the `account signup guide`_
 
178
and `register an SSH key`_ in your new Launchpad account.
 
179
 
 
180
.. _account signup guide: https://help.launchpad.net/CreatingYourLaunchpadAccount
 
181
.. _register an SSH key: https://launchpad.net/people/+me/+editsshkeys
 
182
 
 
183
Replacing ``john.doe`` with your own Launchpad username, type [#]_::
 
184
 
 
185
 $ bzr push lp:~john.doe/+junk/myproject
 
186
 
 
187
.. [#] Use of the ``lp:`` URL scheme requires bzr 0.92 or later.
 
188
 
 
189
**Note:** ``+junk`` means that this branch isn't associated with any particular
 
190
project in Launchpad.
 
191
 
 
192
Now, anyone can create their own copy of your branch by typing::
 
193
 
 
194
 $ bzr branch lp:~john.doe/+junk/myproject
 
195
 
 
196
You can also see information about your branch, including its revision
 
197
history, at https://code.launchpad.net/people/+me/+junk/myproject
 
198
 
189
199
 
190
200
Creating your own copy of another branch
191
201
========================================
192
202
 
193
203
To work with someone else's code, you can make your own copy of their
194
 
branch. Let's take a real-world example, Breezy's GTK interface::
 
204
branch. Let's take a real-world example, Bazaar's GTK interface::
195
205
 
196
 
  $ brz init-shared-repo ~/brz-gtk
197
 
  $ brz branch lp:~brz/brz-gtk/trunk ~/brz-gtk/john
 
206
  $ bzr branch lp:~bzr/bzr-gtk/trunk bzr-gtk.john
198
207
  Branched 292 revision(s).
199
208
 
200
 
Breezy will download all the files and complete revision history from the
201
 
brz-gtk project's trunk branch and create a copy called ``john``.
 
209
Bazaar will download all the files and complete revision history from the
 
210
bzr-gtk project's trunk branch and create a copy called bzr-gtk.john.
202
211
 
203
212
Now, you have your own copy of the branch and can commit changes with
204
213
or without a net connection. You can share your branch at any time by
205
 
publishing it and, if the  brz-gtk team want to use your work, Breezy
 
214
publishing it and, if the  bzr-gtk team want to use your work, Bazaar
206
215
makes it easy for them to merge your branch back into their trunk branch.
207
216
 
208
217
 
215
224
To make sure your branch stays up to date, you should merge changes from
216
225
the parent into your personal branch::
217
226
 
218
 
  $ brz merge
219
 
  Merging from saved parent location: http://bazaar.launchpad.net/~brz/brz-gtk/trunk
 
227
  $ bzr merge
 
228
  Merging from saved parent location: http://bazaar.launchpad.net/~bzr/bzr-gtk/trunk
220
229
  All changes applied successfully.
221
230
 
222
231
Check what has changed::
223
232
 
224
 
  $ brz diff
225
 
 
226
 
If different branches have made changes to the same areas of the same
227
 
files, then merging them may generate conflicts.  When this happens,
228
 
Breezy puts text markers like ``<<<<<<<`` into the files, and records them
229
 
in a list of conflicted files.  You should edit the files to reflect the
230
 
way you want to resolve the conflicts, use ``brz diff`` to check the
231
 
changes, and then ``brz resolve`` to mark them as resolved.
 
233
  $ bzr diff
232
234
 
233
235
If you're happy with the changes, you can commit them to your personal
234
236
branch::
235
237
 
236
 
  $ brz commit -m "Merge from main branch"
 
238
  $ bzr commit -m "Merge from main branch"
237
239
  Committed revision 295.
238
240
 
239
241
 
 
242
Merging your work into the parent branch
 
243
========================================
 
244
 
 
245
After you've worked on your personal branch of bzr-gtk, you may want to
 
246
send your changes back upstream to the project. The easiest way is to
 
247
use a merge directive.
 
248
 
 
249
A merge directive is a machine-readable request to perform a
 
250
particular merge.  It usually contains a patch preview of the merge
 
251
and either contains the necessary revisions, or provides a branch
 
252
where they can be found.
 
253
 
 
254
Replacing ``mycode.patch``, create your merge directive::
 
255
 
 
256
 $ bzr send -o mycode.patch
 
257
 Using saved parent location: http://bazaar.launchpad.net/~bzr/bzr-gtk/trunk
 
258
 
 
259
You can now email the merge directive to the bzr-gtk project who, if
 
260
they choose, can use it merge your work back into the parent branch.
 
261
 
 
262
 
240
263
Learning more
241
264
=============
242
265
 
243
 
You can find out more about Breezy in the
244
 
`Breezy User Guide <../user-guide/index.html>`_.
245
 
 
246
 
To learn about Breezy on the command-line::
247
 
 
248
 
  $ brz help
 
266
You can find out more about Bazaar in the
 
267
`Bazaar User Guide <../user-guide/index.html>`_.
 
268
 
 
269
To learn about Bazaar on the command-line::
 
270
 
 
271
  $ bzr help
 
272
 
 
273
To learn about Bazaar commands::
 
274
 
 
275
  $ bzr help commands
249
276
 
250
277
To learn about the ''foo'' topic or command::
251
278
 
252
 
  $ brz help foo
253
 
 
254
 
Licence
255
 
=======
256
 
 
257
 
Copyright 2007-2011 Canonical Ltd. Breezy is free software, and you
258
 
may use, modify and redistribute both Breezy and this document under
259
 
the terms of the GNU General Public License version 2 or later. See
260
 
<http://www.gnu.org/licenses/>.
 
279
  $ bzr help foo