← 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: John Arbash Meinel
  • Date: 2006-06-10 14:53:51 UTC
  • mto: (1711.7.2 win32)
  • mto: This revision was merged to the branch mainline in revision 1796.
  • Revision ID: john@arbash-meinel.com-20060610145351-9da0c1f8ba8a57e0
the _posix_* routines should use posixpath not os.path, so tests pass on win32

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/>.