← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

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

  • Committer: Patch Queue Manager
  • Date: 2011-09-22 14:12:18 UTC
  • mfrom: (6155.3.1 jam)
  • Revision ID: pqm@pqm.ubuntu.com-20110922141218-86s4uu6nqvourw4f
(jameinel) Cleanup comments bzrlib/smart/__init__.py (John A Meinel)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/mini-tutorial/index.txt
 
1
======================
 
2
Bazaar in five minutes
 
3
======================
 
4
 
 
5
Introduction
 
6
============
 
7
 
 
8
Bazaar is a distributed version control system that makes it easier for
 
9
people to work together on software projects.
 
10
 
 
11
Over the next five minutes, you'll learn how to put your files under
 
12
version control, how to record changes to them, examine your work, publish
 
13
it and send your work for merger into a project's trunk.
 
14
 
 
15
 
 
16
Installation
 
17
============
 
18
 
 
19
This guide doesn't describe how to install Bazaar but it's usually very
 
20
easy. You can find installation instructions at:
 
21
 
 
22
- **GNU/Linux:** Bazaar is probably in your GNU/Linux distribution already.
 
23
- **Windows:** `installation instructions for Windows`_.
 
24
- **Mac OS X:** `installation instructions for Mac OS X`_.
 
25
 
 
26
For other platforms and to install from source code, see the Download_
 
27
and Installation_ pages.
 
28
 
 
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
 
33
 
 
34
 
 
35
Introducing yourself
 
36
====================
 
37
 
 
38
Bazaar 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 Bazaar who you are.  Using your name
 
44
and email address, instead of John Doe's, type::
 
45
 
 
46
  $ bzr whoami "John Doe <john.doe@gmail.com>"
 
47
 
 
48
You can check what identity is stored in Bazaar's configuration::
 
49
 
 
50
  $ bzr whoami
 
51
  John Doe <john.doe@gmail.com>
 
52
 
 
53
 
 
54
Starting a new project
 
55
======================
 
56
 
 
57
Let's suppose we want to store a new project under Bazaar.  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
  bzr init-repo sample
 
69
  cd sample
 
70
  bzr init trunk
 
71
  cd trunk
 
72
 
 
73
 
 
74
Adding files
 
75
============
 
76
 
 
77
Now that we have the trunk, we need to move to that directory and
 
78
create some example files for the first version of that project.  Create
 
79
a file ``test1.txt`` using a text editor (like emacs, nano, or notepad),
 
80
and save it.  Then we'll "add" the file, which tells bzr we want it to
 
81
track changes::
 
82
 
 
83
  bzr add test1.txt
 
84
 
 
85
and then commit, which saves a snapshot of all versioned files::
 
86
 
 
87
  bzr commit -m "Added first line of text"
 
88
 
 
89
 
 
90
Making changes to your files
 
91
============================
 
92
 
 
93
 
 
94
Let's change a file and commit that change to your branch.
 
95
 
 
96
Edit ``test1.txt`` in your favourite editor, then check what have you done::
 
97
 
 
98
 $ bzr diff
 
99
 === modified file 'test1.txt'
 
100
 --- test1.txt   2007-10-08 17:56:14 +0000
 
101
 +++ test1.txt   2007-10-08 17:46:22 +0000
 
102
 @@ -0,0 +1,1 @@
 
103
 +test test test
 
104
 
 
105
Commit your work to the Bazaar branch::
 
106
 
 
107
  $ bzr commit -m "Added first line of text"
 
108
  Committed revision 2.
 
109
 
 
110
 
 
111
Viewing the revision log
 
112
========================
 
113
 
 
114
You can see the history of your branch by browsing its log::
 
115
 
 
116
  $ bzr log
 
117
  ------------------------------------------------------------
 
118
  revno: 2
 
119
  committer: John Doe <john.doe@gmail.com>
 
120
  branch nick: myproject
 
121
  timestamp: Mon 2007-10-08 17:56:14 +0000
 
122
  message:
 
123
    Added first line of text
 
124
  ------------------------------------------------------------
 
125
  revno: 1
 
126
  committer: John Doe <john.doe@gmail.com>
 
127
  branch nick: myproject
 
128
  timestamp: Mon 2006-10-08 17:46:22 +0000
 
129
  message:
 
130
    Initial import
 
131
 
 
132
 
 
133
Publishing your branch on Launchpad
 
134
===================================
 
135
 
 
136
Launchpad is a suite of development and hosting tools for
 
137
software projects. You can use it to publish your branch.  (You can 
 
138
also publish branches onto your own server or other hosting services.)
 
139
 
 
140
If you don't have a Launchpad account, follow the `account signup guide`_
 
141
and `register an SSH key`_ in your new Launchpad account.
 
142
 
 
143
.. _account signup guide: https://help.launchpad.net/CreatingYourLaunchpadAccount
 
144
.. _register an SSH key: https://launchpad.net/people/+me/+editsshkeys
 
145
 
 
146
Replacing ``john.doe`` with your own Launchpad username, type::
 
147
 
 
148
 $ bzr push lp:~john.doe/+junk/myproject
 
149
 
 
150
**Note**: ``+junk`` is a place to store experimental branches not
 
151
associated with any particular project.  Normally, you should push a
 
152
project into an existing project, or register a new project through the
 
153
web interface.
 
154
 
 
155
Now, anyone can create their own copy of your branch by typing::
 
156
 
 
157
 $ bzr branch lp:~john.doe/+junk/myproject
 
158
 
 
159
You can also see information about your branch, including its revision
 
160
history, at https://code.launchpad.net/people/+me/+junk/myproject
 
161
 
 
162
 
 
163
Creating your own copy of another branch
 
164
========================================
 
165
 
 
166
To work with someone else's code, you can make your own copy of their
 
167
branch. Let's take a real-world example, Bazaar's GTK interface::
 
168
 
 
169
  $ bzr init-repo ~/bzr-gtk
 
170
  $ bzr branch lp:~bzr/bzr-gtk/trunk ~/bzr-gtk/john
 
171
  Branched 292 revision(s).
 
172
 
 
173
Bazaar will download all the files and complete revision history from the
 
174
bzr-gtk project's trunk branch and create a copy called ``john``.
 
175
 
 
176
Now, you have your own copy of the branch and can commit changes with
 
177
or without a net connection. You can share your branch at any time by
 
178
publishing it and, if the  bzr-gtk team want to use your work, Bazaar
 
179
makes it easy for them to merge your branch back into their trunk branch.
 
180
 
 
181
 
 
182
Updating your branch from the main branch
 
183
=========================================
 
184
 
 
185
While you commit changes to your branch, it's likely that other people will
 
186
also continue to commit code to the parent branch.
 
187
 
 
188
To make sure your branch stays up to date, you should merge changes from
 
189
the parent into your personal branch::
 
190
 
 
191
  $ bzr merge
 
192
  Merging from saved parent location: http://bazaar.launchpad.net/~bzr/bzr-gtk/trunk
 
193
  All changes applied successfully.
 
194
 
 
195
Check what has changed::
 
196
 
 
197
  $ bzr diff
 
198
 
 
199
If different branches have made changes to the same areas of the same
 
200
files, then merging them may generate conflicts.  When this happens,
 
201
Bazaar puts text markers like ``<<<<<<<`` into the files, and records them
 
202
in a list of conflicted files.  You should edit the files to reflect the
 
203
way you want to resolve the conflicts, use ``bzr diff`` to check the
 
204
changes, and then ``bzr resolve`` to mark them as resolved.
 
205
 
 
206
If you're happy with the changes, you can commit them to your personal
 
207
branch::
 
208
 
 
209
  $ bzr commit -m "Merge from main branch"
 
210
  Committed revision 295.
 
211
 
 
212
 
 
213
Learning more
 
214
=============
 
215
 
 
216
You can find out more about Bazaar in the
 
217
`Bazaar User Guide <../user-guide/index.html>`_.
 
218
 
 
219
To learn about Bazaar on the command-line::
 
220
 
 
221
  $ bzr help
 
222
 
 
223
To learn about the ''foo'' topic or command::
 
224
 
 
225
  $ bzr help foo
 
226
 
 
227
Licence
 
228
=======
 
229
 
 
230
Copyright 2007-2011 Canonical Ltd. Bazaar is free software, and you
 
231
may use, modify and redistribute both Bazaar and this document under
 
232
the terms of the GNU General Public License version 2 or later. See
 
233
<http://www.gnu.org/licenses/>.