/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: Jelmer Vernooij
  • Date: 2018-07-08 10:56:06 UTC
  • mto: This revision was merged to the branch mainline in revision 7030.
  • Revision ID: jelmer@jelmer.uk-20180708105606-d53hkks89qq88twu
Use separate .as_bytes method rather than __bytes__.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/mini-tutorial/index.txt
1
1
======================
2
 
Bazaar in five minutes
 
2
Breezy in five minutes
3
3
======================
4
4
 
5
5
Introduction
6
6
============
7
7
 
8
 
Bazaar is a distributed version control system that makes it easier for
 
8
Breezy 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
 
 
18
15
 
19
16
Installation
20
17
============
21
18
 
22
 
This guide doesn't describe how to install Bazaar but it's usually very
 
19
This guide doesn't describe how to install Breezy but it's usually very
23
20
easy. You can find installation instructions at:
24
21
 
25
 
- **GNU/Linux:** Bazaar is probably in your GNU/Linux distribution already.
 
22
- **GNU/Linux:** Breezy is probably in your GNU/Linux distribution already.
26
23
- **Windows:** `installation instructions for Windows`_.
27
24
- **Mac OS X:** `installation instructions for Mac OS X`_.
28
25
 
29
26
For other platforms and to install from source code, see the Download_
30
27
and Installation_ pages.
31
28
 
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
 
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
36
33
 
37
34
 
38
35
Introducing yourself
39
36
====================
40
37
 
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
 
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
54
51
  John Doe <john.doe@gmail.com>
55
52
 
56
53
 
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.
 
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-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.
99
96
 
100
97
 
101
98
Making changes to your files
102
99
============================
103
100
 
 
101
 
104
102
Let's change a file and commit that change to your branch.
105
103
 
106
 
Edit ``test1.txt`` in your favourite editor, then check what have you done::
107
 
 
108
 
 $ bzr diff
 
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
109
115
 === modified file 'test1.txt'
110
116
 --- test1.txt   2007-10-08 17:56:14 +0000
111
117
 +++ test1.txt   2007-10-08 17:46:22 +0000
112
118
 @@ -0,0 +1,1 @@
113
119
 +test test test
114
120
 
115
 
Commit your work to the Bazaar branch::
116
 
 
117
 
  $ bzr commit -m "Added first line of text"
118
 
  Committed revision 2.
119
 
 
 
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.
120
127
 
121
128
Viewing the revision log
122
129
========================
123
130
 
124
131
You can see the history of your branch by browsing its log::
125
132
 
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
 
  ------------------------------------------------------------
 
133
  $ brz log
135
134
  revno: 1
136
135
  committer: John Doe <john.doe@gmail.com>
137
 
  branch nick: myproject
 
136
  branch nick: trunk
138
137
  timestamp: Mon 2006-10-08 17:46:22 +0000
139
138
  message:
140
139
    Initial import
141
140
 
142
141
 
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
 
 
 
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
199
189
 
200
190
Creating your own copy of another branch
201
191
========================================
202
192
 
203
193
To work with someone else's code, you can make your own copy of their
204
 
branch. Let's take a real-world example, Bazaar's GTK interface::
 
194
branch. Let's take a real-world example, Breezy's GTK interface::
205
195
 
206
 
  $ bzr branch lp:~bzr/bzr-gtk/trunk bzr-gtk.john
 
196
  $ brz init-repo ~/brz-gtk
 
197
  $ brz branch lp:~brz/brz-gtk/trunk ~/brz-gtk/john
207
198
  Branched 292 revision(s).
208
199
 
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.
 
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``.
211
202
 
212
203
Now, you have your own copy of the branch and can commit changes with
213
204
or without a net connection. You can share your branch at any time by
214
 
publishing it and, if the  bzr-gtk team want to use your work, Bazaar
 
205
publishing it and, if the  brz-gtk team want to use your work, Breezy
215
206
makes it easy for them to merge your branch back into their trunk branch.
216
207
 
217
208
 
224
215
To make sure your branch stays up to date, you should merge changes from
225
216
the parent into your personal branch::
226
217
 
227
 
  $ bzr merge
228
 
  Merging from saved parent location: http://bazaar.launchpad.net/~bzr/bzr-gtk/trunk
 
218
  $ brz merge
 
219
  Merging from saved parent location: http://bazaar.launchpad.net/~brz/brz-gtk/trunk
229
220
  All changes applied successfully.
230
221
 
231
222
Check what has changed::
232
223
 
233
 
  $ bzr diff
 
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.
234
232
 
235
233
If you're happy with the changes, you can commit them to your personal
236
234
branch::
237
235
 
238
 
  $ bzr commit -m "Merge from main branch"
 
236
  $ brz commit -m "Merge from main branch"
239
237
  Committed revision 295.
240
238
 
241
239
 
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
 
 
263
240
Learning more
264
241
=============
265
242
 
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
 
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
276
249
 
277
250
To learn about the ''foo'' topic or command::
278
251
 
279
 
  $ bzr help foo
 
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/>.