~bzr-pqm/bzr/bzr.dev : revision 5908

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

If you'd prefer a more detailed introduction, take a look at

16

`Learning More`_.

17

18

15

19

16

Installation

20

17

============

38

35

Introducing yourself

39

36

====================

40

37

41

Before you start working, it is good to tell Bazaar who you are. That

42

way your work is properly identified in revision logs.

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

43

42

44

Using your name and email address, instead of John Doe's, type::

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

Bazaar will now create or modify a configuration file, including your

49

name and email address.

50

51

Now, check that your name and email address are correctly registered::

48

You can check what identity is stored in Bazaar's configuration::

52

49

53

50

$ bzr whoami

54

51

John Doe <john.doe@gmail.com>

55

52

56

53

57

Putting files under version control

58

===================================

59

60

Let's create a directory and some files to use with Bazaar::

61

62

$ mkdir myproject

63

$ cd myproject

64

$ mkdir subdirectory

65

$ touch test1.txt test2.txt test3.txt subdirectory/test4.txt

66

67

**Note for Windows users**: use Windows Explorer to create your

68

directories, then right-click in those directories and select

69

``New file`` to create your files.

70

71

Now get Bazaar to initialize itself in your project directory::

72

73

$ bzr init

74

75

If it looks like nothing happened, don't worry. Bazaar has created a

76

branch_ where it will store your files and their revision histories.

77

78

.. _branch: http://wiki.bazaar.canonical.com/Branch

79

80

The next step is to tell Bazaar which files you want to track. Running

81

``bzr add`` will recursively add everything in the project::

82

83

$ bzr add

84

added subdirectory

85

added test1.txt

86

added test2.txt

87

added test3.txt

88

added subdirectory/test4.txt

89

90

Next, take a snapshot of your files by committing them to your branch. Add

91

a message to explain why you made the commit::

92

93

$ bzr commit -m "Initial import"

94

95

As Bazaar is a distributed version control system, it doesn't need to

96

connect to a central server to make the commit. Instead, Bazaar stores your

97

branch and all its commits inside the directory you're working with; look

98

for the ``.bzr`` sub-directory.

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

99

67

100

68

101

69

Making changes to your files

153

121

.. _account signup guide: https://help.launchpad.net/CreatingYourLaunchpadAccount

154

122

.. _register an SSH key: https://launchpad.net/people/+me/+editsshkeys

155

123

156

Replacing ``john.doe`` with your own Launchpad username, type [#]_::

124

Replacing ``john.doe`` with your own Launchpad username, type::

157

125

158

126

$ bzr push lp:~john.doe/+junk/myproject

159

127

160

.. [#] Use of the ``lp:`` URL scheme requires bzr 0.92 or later.

161

162

**Note**: ``+junk`` means that this branch isn't associated with any particular

163

project in Launchpad.

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.

164

132

165

133

Now, anyone can create their own copy of your branch by typing::

166

134

170

138

history, at https://code.launchpad.net/people/+me/+junk/myproject

171

139

172

140

173

174

175

141

Creating your own copy of another branch

176

142

========================================

177

143

178

144

To work with someone else's code, you can make your own copy of their

179

145

branch. Let's take a real-world example, Bazaar's GTK interface::

180

146

181

$ bzr branch lp:~bzr/bzr-gtk/trunk bzr-gtk.john

147

$ bzr init-repo ~/bzr-gtk

148

$ bzr branch lp:~bzr/bzr-gtk/trunk ~/bzr-gtk/john

182

149

Branched 292 revision(s).

183

150

184

151

Bazaar will download all the files and complete revision history from the

185

bzr-gtk project's trunk branch and create a copy called bzr-gtk.john.

152

bzr-gtk project's trunk branch and create a copy called ``john``.

186

153

187

154

Now, you have your own copy of the branch and can commit changes with

188

155

or without a net connection. You can share your branch at any time by

207

174

208

175

$ bzr diff

209

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

210

184

If you're happy with the changes, you can commit them to your personal

211

185

branch::

212

186

214

188

Committed revision 295.

215

189

216

190

217

Merging your work into the parent branch

218

========================================

219

220

After you've worked on your personal branch of bzr-gtk, you may want to

221

send your changes back upstream to the project. The easiest way is to

222

use a merge directive.

223

224

A merge directive is a machine-readable request to perform a

225

particular merge. It usually contains a patch preview of the merge

226

and either contains the necessary revisions, or provides a branch

227

where they can be found.

228

229

Replacing ``mycode.patch``, create your merge directive::

230

231

$ bzr send -o mycode.patch

232

Using saved parent location: http://bazaar.launchpad.net/~bzr/bzr-gtk/trunk

233

234

You can now email the merge directive to the bzr-gtk project who, if

235

they choose, can use it merge your work back into the parent branch.

236

237

238

191

Learning more

239

192

=============

240

193

245

198

246

199

$ bzr help

247

200

248

To learn about Bazaar commands::

249

250

$ bzr help commands

251

252

201

To learn about the ''foo'' topic or command::

253

202

254

203

$ bzr help foo

255

204

256

205

Licence

257

=============

206

=======

258

207

259

208

260

209

may use, modify and redistribute both Bazaar and this document under