← 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: Ian Clatworthy
  • Date: 2007-08-13 14:16:53 UTC
  • mto: (2733.1.1 ianc-integration)
  • mto: This revision was merged to the branch mainline in revision 2734.
  • Revision ID: ian.clatworthy@internode.on.net-20070813141653-3cbrp00xowq58zv1
Added mini tutorial

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/mini-tutorial/index.txt
 
1
====================
 
2
Bazaar Mini Tutorial
 
3
====================
 
4
 
 
5
.. contents::
 
6
 
 
7
Introduction
 
8
============
 
9
 
 
10
This is a very brief 5-minute tutorial, covering only what a first time user
 
11
needs to start a project or start contributing to a project using Bazaar.
 
12
For a more detailed look, see `Learning More`_.
 
13
 
 
14
 
 
15
Installation
 
16
============
 
17
 
 
18
See http://bazaar-vcs.org/Download. Bazaar is probably in your GNU/Linux
 
19
distribution already. If not, it's trivial to install on any platform that
 
20
runs Python 2.4, including Windows. Installation should take at most a few
 
21
minutes.
 
22
 
 
23
 
 
24
Introducing Yourself
 
25
====================
 
26
 
 
27
You want Bazaar to correctly identify you in revision logs. Using your name
 
28
and email instead of Joe Doe's, type::
 
29
 
 
30
  $ bzr whoami "Joe Doe <joe.doe@gmail.com>"
 
31
 
 
32
Now try::
 
33
 
 
34
  $ bzr whoami
 
35
  Joe Doe <joe.doe@gmail.com>
 
36
 
 
37
 
 
38
Putting Existing Files Under Version Control
 
39
============================================
 
40
 
 
41
It is very easy to put an existing set of files under version control using
 
42
Bazaar::
 
43
 
 
44
  $ cd my-project
 
45
  $ bzr init .
 
46
  $ bzr add
 
47
  $ bzr commit -m "Initial import"
 
48
 
 
49
You can now make changes, track them, publish your branch and so on as
 
50
explained below.
 
51
 
 
52
 
 
53
Creating A Personal Branch
 
54
==========================
 
55
 
 
56
Rather than starting a new project, you may wish to work on an existing
 
57
project either you or someone else has published.
 
58
 
 
59
Create a branch of an existing project::
 
60
 
 
61
  $ bzr branch http://example.com/code/foobar.dev foobar.joe
 
62
  Branched 1 revision(s).                                                        
 
63
 
 
64
Note that after you create a personal branch, you don't need web access to
 
65
commit changes.
 
66
 
 
67
 
 
68
Making Changes
 
69
==============
 
70
 
 
71
Edit a file::
 
72
 
 
73
  $ cd foobar.joe
 
74
  $ hack...
 
75
 
 
76
Check what have you done::
 
77
 
 
78
  $ bzr diff
 
79
  === modified file 'foo.c'
 
80
  --- foo.c
 
81
  +++ foo.c
 
82
  @@ -30,6 +30,7 @@
 
83
 
 
84
   #include "foo.h"
 
85
 
 
86
  +
 
87
   static PyObject *
 
88
   _pyfribidi_log2vis (PyObject * self, PyObject * args, PyObject * kw)
 
89
   {
 
90
 
 
91
Commit your hard work::
 
92
 
 
93
  $ bzr commit -m 'added some whitespace'
 
94
  Committed revision 2.
 
95
 
 
96
 
 
97
Viewing the Revision Log
 
98
========================
 
99
 
 
100
Browse the history of the branch::
 
101
 
 
102
  $ bzr log
 
103
  ------------------------------------------------------------
 
104
  revno: 2
 
105
  committer: Joe Doe <joe.doe@gmail.com>
 
106
  branch nick: foobar.joe
 
107
  timestamp: Mon 2006-02-06 01:33:35 +0200
 
108
  message:
 
109
    added some whitespace
 
110
  ------------------------------------------------------------
 
111
  revno: 1
 
112
  committer: James Hacker <jmh@example.com>
 
113
  branch nick: foobar.dev
 
114
  timestamp: Mon 2006-02-06 01:06:11 +0200
 
115
  message:
 
116
    initial revision
 
117
 
 
118
 
 
119
Updating Your Branch from the Main Branch
 
120
=========================================
 
121
 
 
122
While you work hard on your branch, others may have committed new code to the
 
123
main branch. From time to time, you want to merge changes from the main
 
124
branch into your branch::
 
125
 
 
126
  $ bzr merge
 
127
  Using saved location: http://example.com/code/foobar.dev
 
128
  All changes applied successfully.
 
129
            
 
130
What was changed locally by merging the main branch?
 
131
 
 
132
::
 
133
 
 
134
  $ bzr diff
 
135
  === modified file 'pyfribidi.c'
 
136
  --- pyfribidi.c
 
137
  +++ pyfribidi.c
 
138
  @@ -236,6 +236,7 @@
 
139
          PyMem_Del (logical);
 
140
          PyMem_Del (visual);
 
141
   
 
142
  +    /* evil hack! */
 
143
          return result;
 
144
   }
 
145
 
 
146
Commit the changes from the main branch::
 
147
 
 
148
  $ bzr commit -m 'merge from main branch'
 
149
  Committed revision 6.
 
150
 
 
151
Note that you may occasionally need to resolve conflicts or make other minor
 
152
changes (so tests pass say) before committing. For these reasons, merge does
 
153
not implicitly commit.
 
154
 
 
155
 
 
156
Publishing Your Branch
 
157
======================
 
158
 
 
159
You can simply use rsync to copy your branch to a web server, but using
 
160
``bzr push`` is the easiest way. Let's assume you want to publish your
 
161
branch in jod.example.com/foobar.joe and you have sftp access to the server::
 
162
 
 
163
  $ bzr push sftp://jod@jod.example.com/public_html/foobar.joe/
 
164
  2 revision(s) pushed.
 
165
    
 
166
Note that to use sftp, your may need to install ''paramiko'' and ''pyCrypto''.
 
167
See http://bazaar-vcs.org/InstallationFaq for details.
 
168
 
 
169
Now anyone can get your branch with (try it yourself!)::
 
170
 
 
171
  bzr branch http://jod.example.com/foobar.joe/
 
172
 
 
173
 
 
174
Learning More
 
175
=============
 
176
 
 
177
To learn about bzr topics::
 
178
 
 
179
  $ bzr help
 
180
 
 
181
To learn about bzr commands::
 
182
 
 
183
  $ bzr help commands
 
184
 
 
185
To learn about the ''foo'' topic or command::
 
186
 
 
187
  $ bzr help foo
 
188
 
 
189
Alternatively, browse the `Bazaar Documentation <../../index.html>`_.