/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: Gustav Hartvigsson
  • Date: 2021-01-09 21:36:27 UTC
  • Revision ID: gustav.hartvigsson@gmail.com-20210109213627-h1xwcutzy9m7a99b
Added 'Case Preserving Working Tree Use Cases' from Canonical Wiki

* Addod a page from the Canonical Bazaar wiki
  with information on the scmeatics of case
  perserving filesystems an a case insensitive
  filesystem works.
  
  * Needs re-work, but this will do as it is the
    same inforamoton as what was on the linked
    page in the currint documentation.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/mini-tutorial/index.txt
 
1
======================
 
2
Breezy in five minutes
 
3
======================
 
4
 
 
5
Introduction
 
6
============
 
7
 
 
8
Breezy 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 Breezy but it's usually very
 
20
easy. You can find installation instructions at:
 
21
 
 
22
- **GNU/Linux:** Breezy 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
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
 
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 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-shared-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.
 
96
 
 
97
 
 
98
Making changes to your files
 
99
============================
 
100
 
 
101
 
 
102
Let's change a file and commit that change to your branch.
 
103
 
 
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
 
115
 === modified file 'test1.txt'
 
116
 --- test1.txt   2007-10-08 17:56:14 +0000
 
117
 +++ test1.txt   2007-10-08 17:46:22 +0000
 
118
 @@ -0,0 +1,1 @@
 
119
 +test test test
 
120
 
 
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.
 
127
 
 
128
Viewing the revision log
 
129
========================
 
130
 
 
131
You can see the history of your branch by browsing its log::
 
132
 
 
133
  $ brz log
 
134
  revno: 1
 
135
  committer: John Doe <john.doe@gmail.com>
 
136
  branch nick: trunk
 
137
  timestamp: Mon 2006-10-08 17:46:22 +0000
 
138
  message:
 
139
    Initial import
 
140
 
 
141
 
 
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
 
189
 
 
190
Creating your own copy of another branch
 
191
========================================
 
192
 
 
193
To work with someone else's code, you can make your own copy of their
 
194
branch. Let's take a real-world example, Breezy's GTK interface::
 
195
 
 
196
  $ brz init-shared-repo ~/brz-gtk
 
197
  $ brz branch lp:~brz/brz-gtk/trunk ~/brz-gtk/john
 
198
  Branched 292 revision(s).
 
199
 
 
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``.
 
202
 
 
203
Now, you have your own copy of the branch and can commit changes with
 
204
or without a net connection. You can share your branch at any time by
 
205
publishing it and, if the  brz-gtk team want to use your work, Breezy
 
206
makes it easy for them to merge your branch back into their trunk branch.
 
207
 
 
208
 
 
209
Updating your branch from the main branch
 
210
=========================================
 
211
 
 
212
While you commit changes to your branch, it's likely that other people will
 
213
also continue to commit code to the parent branch.
 
214
 
 
215
To make sure your branch stays up to date, you should merge changes from
 
216
the parent into your personal branch::
 
217
 
 
218
  $ brz merge
 
219
  Merging from saved parent location: http://bazaar.launchpad.net/~brz/brz-gtk/trunk
 
220
  All changes applied successfully.
 
221
 
 
222
Check what has changed::
 
223
 
 
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.
 
232
 
 
233
If you're happy with the changes, you can commit them to your personal
 
234
branch::
 
235
 
 
236
  $ brz commit -m "Merge from main branch"
 
237
  Committed revision 295.
 
238
 
 
239
 
 
240
Learning more
 
241
=============
 
242
 
 
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
 
249
 
 
250
To learn about the ''foo'' topic or command::
 
251
 
 
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/>.