← 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: Martin Pool
  • Date: 2005-07-22 23:32:00 UTC
  • Revision ID: mbp@sourcefrog.net-20050722233200-ccdeca985093a9fb
- now needs python 2.4
- update instructions for running selftest

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 directory to hold all our work related to this project.  We'll make
59
 
a *repository directory*, which means that the 
60
 
 
61
 
::
62
 
 
63
 
  bzr init-repo sample
64
 
  cd sample
65
 
  bzr init trunk
66
 
  cd trunk
67
 
 
68
 
 
69
 
Making changes to your files
70
 
============================
71
 
 
72
 
Let's change a file and commit that change to your branch.
73
 
 
74
 
Edit ``test1.txt`` in your favourite editor, then check what have you done::
75
 
 
76
 
 $ bzr diff
77
 
 === modified file 'test1.txt'
78
 
 --- test1.txt   2007-10-08 17:56:14 +0000
79
 
 +++ test1.txt   2007-10-08 17:46:22 +0000
80
 
 @@ -0,0 +1,1 @@
81
 
 +test test test
82
 
 
83
 
Commit your work to the Bazaar branch::
84
 
 
85
 
  $ bzr commit -m "Added first line of text"
86
 
  Committed revision 2.
87
 
 
88
 
 
89
 
Viewing the revision log
90
 
========================
91
 
 
92
 
You can see the history of your branch by browsing its log::
93
 
 
94
 
  $ bzr log
95
 
  ------------------------------------------------------------
96
 
  revno: 2
97
 
  committer: John Doe <john.doe@gmail.com>
98
 
  branch nick: myproject
99
 
  timestamp: Mon 2007-10-08 17:56:14 +0000
100
 
  message:
101
 
    Added first line of text
102
 
  ------------------------------------------------------------
103
 
  revno: 1
104
 
  committer: John Doe <john.doe@gmail.com>
105
 
  branch nick: myproject
106
 
  timestamp: Mon 2006-10-08 17:46:22 +0000
107
 
  message:
108
 
    Initial import
109
 
 
110
 
 
111
 
Publishing your branch on Launchpad
112
 
===================================
113
 
 
114
 
Launchpad is a suite of development and hosting tools for
115
 
software projects. You can use it to publish your branch.  (You can 
116
 
also publish branches onto your own server or other hosting services.)
117
 
 
118
 
If you don't have a Launchpad account, follow the `account signup guide`_
119
 
and `register an SSH key`_ in your new Launchpad account.
120
 
 
121
 
.. _account signup guide: https://help.launchpad.net/CreatingYourLaunchpadAccount
122
 
.. _register an SSH key: https://launchpad.net/people/+me/+editsshkeys
123
 
 
124
 
Replacing ``john.doe`` with your own Launchpad username, type::
125
 
 
126
 
 $ bzr push lp:~john.doe/+junk/myproject
127
 
 
128
 
**Note**: ``+junk`` is a place to store experimental branches not
129
 
associated with any particular project.  Normally, you should push a
130
 
project into an existing project, or register a new project through the
131
 
web interface.
132
 
 
133
 
Now, anyone can create their own copy of your branch by typing::
134
 
 
135
 
 $ bzr branch lp:~john.doe/+junk/myproject
136
 
 
137
 
You can also see information about your branch, including its revision
138
 
history, at https://code.launchpad.net/people/+me/+junk/myproject
139
 
 
140
 
 
141
 
Creating your own copy of another branch
142
 
========================================
143
 
 
144
 
To work with someone else's code, you can make your own copy of their
145
 
branch. Let's take a real-world example, Bazaar's GTK interface::
146
 
 
147
 
  $ bzr init-repo ~/bzr-gtk
148
 
  $ bzr branch lp:~bzr/bzr-gtk/trunk ~/bzr-gtk/john
149
 
  Branched 292 revision(s).
150
 
 
151
 
Bazaar will download all the files and complete revision history from the
152
 
bzr-gtk project's trunk branch and create a copy called ``john``.
153
 
 
154
 
Now, you have your own copy of the branch and can commit changes with
155
 
or without a net connection. You can share your branch at any time by
156
 
publishing it and, if the  bzr-gtk team want to use your work, Bazaar
157
 
makes it easy for them to merge your branch back into their trunk branch.
158
 
 
159
 
 
160
 
Updating your branch from the main branch
161
 
=========================================
162
 
 
163
 
While you commit changes to your branch, it's likely that other people will
164
 
also continue to commit code to the parent branch.
165
 
 
166
 
To make sure your branch stays up to date, you should merge changes from
167
 
the parent into your personal branch::
168
 
 
169
 
  $ bzr merge
170
 
  Merging from saved parent location: http://bazaar.launchpad.net/~bzr/bzr-gtk/trunk
171
 
  All changes applied successfully.
172
 
 
173
 
Check what has changed::
174
 
 
175
 
  $ bzr diff
176
 
 
177
 
If different branches have made changes to the same areas of the same
178
 
files, then merging them may generate conflicts.  When this happens,
179
 
Bazaar puts text markers like ``<<<<<<<`` into the files, and records them
180
 
in a list of conflicted files.  You should edit the files to reflect the
181
 
way you want to resolve the conflicts, use ``bzr diff`` to check the
182
 
changes, and then ``bzr resolve`` to mark them as resolved.
183
 
 
184
 
If you're happy with the changes, you can commit them to your personal
185
 
branch::
186
 
 
187
 
  $ bzr commit -m "Merge from main branch"
188
 
  Committed revision 295.
189
 
 
190
 
 
191
 
Learning more
192
 
=============
193
 
 
194
 
You can find out more about Bazaar in the
195
 
`Bazaar User Guide <../user-guide/index.html>`_.
196
 
 
197
 
To learn about Bazaar on the command-line::
198
 
 
199
 
  $ bzr help
200
 
 
201
 
To learn about the ''foo'' topic or command::
202
 
 
203
 
  $ bzr help foo
204
 
 
205
 
Licence
206
 
=======
207
 
 
208
 
Copyright 2007-2011 Canonical Ltd. Bazaar is free software, and you
209
 
may use, modify and redistribute both Bazaar and this document under
210
 
the terms of the GNU General Public License version 2 or later. See
211
 
<http://www.gnu.org/licenses/>.