~ubuntu-branches/ubuntu/saucy/ubuntu-docs/saucy-proposed

Version control is the art of managing changes to information. It has long been a critical tool for programmers, who typically spend their time making small changes to software and then undoing those changes the next day. But the usefulness of version control software extends far beyond the bounds of the software development world. Anywhere you can find people using computers to manage information that changes often, there is room for version control.</para>

<title>Bazaar</title>

<para>

Bazaar is a new version control system sponsored by Canonical, the

commercial company behind Ubuntu. Unlike Subversion and CVS that

only support a central repository model, Bazaar also supports

<emphasis>distributed version control</emphasis>, giving people

the ability to collaborate more efficiently. In particular,

Bazaar is designed to maximize the level of community participation

in open source projects.

</para>

<title>Installation</title>

<para>

At a terminal prompt, enter the following command to install

<application>bzr</application>:

<command>sudo apt-get install bzr</command>

</screen>

</para>

</sect2>

<title>Configuration</title>

<para>

To introduce yourself to <application>bzr</application>,

use the <emphasis>whoami</emphasis> command like this:

<command>$ bzr whoami 'Joe Doe <joe.doe@gmail.com>'</command>

</screen>

</para>

</sect2>

<title>Learning Bazaar</title>

<para>

Bazaar comes with bundled documentation installed into

<application>/usr/share/doc/bzr/html</application> by default.

The tutorial is a good place to start. The

<application>bzr</application> command also comes with

built-in help:

</screen>

</para>

<para>

To learn more about the <emphasis>foo</emphasis> command:

</screen>

</para>

</sect2>

<title>Launchpad Integration</title>

<para>

While highly useful as a stand-alone system, Bazaar has good, optional

integration with <ulink url="https://launchpad.net/">Launchpad</ulink>,

the collaborative development system used by Canonical and the

broader open source community to manage and extend Ubuntu itself.

For information on how Bazaar can be used with Launchpad to

collaborate on open source projects, see

http://bazaar-vcs.org/LaunchpadIntegration</ulink>.</para>

</sect2>

</sect1>

<title>Subversion</title>

<para>

Subversion is an open source version control system. Using Subversion, you can record the history of source files and documents. It manages files and directories over time. A tree of files is placed into a central repository. The repository is much like an ordinary file server, except that it remembers every change ever made to files and directories.

</para>

<title>Installation</title>

<para>

To access Subversion repository using the HTTP protocol, you must install and

configure a web server. Apache2 is proven to work with Subversion. Please

refer to the HTTP subsection in the Apache2 section to install and configure

Apache2. To access the Subversion repository using the HTTPS protocol, you

must install and configure a digital certificate in your Apache 2 web server.

Please refer to the HTTPS subsection in the Apache2 section to install and

configure the digital certificate.

</para>

<para>

To install Subversion, run the following command from a terminal prompt:

</para>

<para>

100

101

<command>sudo apt-get install subversion libapache2-svn</command>

102

</screen>

103

</para>

104

105

</sect2>

106

107

<title>Server Configuration</title>

108

<para>

109

This step assumes you have installed above mentioned packages on your system. This section explains how to create a Subversion repository and access the project.</para>

110

111

<title>Create Subversion Repository</title>

112

<para>The Subversion repository can be created using the following command from a terminal prompt:</para>

113

114

<para>

115

116

<command>svnadmin create /path/to/repos/project</command>

117

</screen>

118

</para>

119

</sect3>

120

121

<title>Importing Files</title>

122

<para>

123

Once you create the repository you can

124

<emphasis>import</emphasis> files into the

125

repository. To import a directory, enter the

126

following from a terminal prompt:

127

128

<command>svn import /path/to/import/directory file:///path/to/repos/project</command>

129

</screen>

130

</para>

131

</sect3>

132

</sect2>

133

134

<title>Access Methods</title>

135

<para>Subversion repositories can be accessed (checked out) through many

136

different methods --on local disk, or through various network protocols.

137

A repository location, however, is always a URL. The table describes how

138

different URL schemes map to the available access methods.</para>

139

<table><title>Access Methods</title>

140

141

142

143

144

<thead>

145

<row>

146

<entry><para>Schema</para></entry>

147

<entry><para>Access Method</para></entry>

148

</row>

149

</thead>

150

<tbody>

151

<row>

152

153

<entry><para>direct repository access (on local disk)</para></entry>

154

</row>

155

<row>

156

157

<entry><para>Access via WebDAV protocol to Subversion-aware Apache2 web server</para></entry>

158

</row>

159

<row>

160

<entry><para>https://</para></entry>

161

<entry><para>Same as http://, but with SSL encryption</para></entry>

162

</row>

163

<row>

164

165

<entry><para>Access via custom protocol to an svnserve server</para></entry>

166

</row>

167

<row>

168

169

<entry><para>Same as svn://, but through an SSH tunnel</para></entry>

170

</row>

171

</tbody>

172

</tgroup>

173

</table>

174

175

<para>

176

In this section, we will see how to configure Subversion for all

177

these access methods. Here, we cover the basics. For more advanced

178

usage details, refer to the <ulink

179

url="http://svnbook.red-bean.com/">svn book</ulink>.

180

</para>

181

182

<title>Direct repository access (file://)</title>

183

<para> This is the simplest of all access methods. It does not

184

require any Subversion server process to be running. This access

185

method is used to access Subversion from the same machine. The

186

syntax of the command, entered at a terminal prompt, is as follows:</para>

187

188

<para>

189

190

<command>svn co file:///path/to/repos/project</command>

191

</screen>

192

</para>

193

194

<para>

195

196

<command>svn co file://localhost/path/to/repos/project</command>

197

</screen>

198

</para>

199

<note>

200

<para>If you do not specify the hostname, there are three forward slashes (///) -- two for the protocol (file, in this case) plus the leading slash in the path. If you specify the hostname, you must use two forward slashes (//).</para>

201

</note>

202

<para>The repository permissions depend on filesystem permissions. If the user has read/write permission, he can checkout from and commit to the repository.</para>

203

</sect3>

204

205

<title>Access via WebDAV protocol (http://)</title>

206

<para>

207

To access the Subversion repository via WebDAV protocol, you must configure your Apache 2 web server. Add the following snippet between the

208

<emphasis><VirtualHost></emphasis> and <emphasis></VirtualHost></emphasis> elements in

209

<filename>/etc/apache2/sites-available/default</filename>, or another VirtualHost file:

210

</para>

211

212

213

214

DAV svn

215

SVNPath /home/svn

216

AuthType Basic

217

AuthName "Your repository name"

218

AuthUserFile /etc/subversion/passwd

219

Require valid-user

220

</Location>

221

</programlisting>

222

<note>

223

<para>The above configuration snippet assumes that Subversion

224

repositories are created under <filename>/home/svn/</filename>

225

directory using <command>svnadmin</command> command. They can be

226

accessible using <command>http://hostname/svn/repos_name</command>

227

url.</para>

228

</note>

229

<para>

230

To import or commit files to your Subversion repository over

231

HTTP, the repository should be owned by the HTTP user. In

232

Ubuntu systems, normally the HTTP user is

233

<command>www-data</command>. To change the ownership of the

234

repository files enter the following command from terminal

235

prompt:

236

</para>

237

238

<command>sudo chown -R www-data:www-data /path/to/repos</command>

239

</screen>

240

<note>

241

<para>

242

By changing the ownership of repository as

243

<command>www-data</command> you will not be able to import or

244

commit files into the repository by running <command>svn import

245

file:///</command> command as any user other than

246

<command>www-data</command>.

247

</para>

248

</note>

249

250

<para>

251

Next, you must create the <filename>/etc/subversion/passwd</filename> file that will contain user authentication details.

252

To create a file issue the following command at a command prompt (which will create the file and add the first user):

253

</para>

254

255

256

<command>sudo htpasswd -c /etc/subversion/passwd user_name</command>

257

</screen>

258

259

<para>

260

To add additional users omit the <emphasis>"-c"</emphasis> option as this option replaces the old file. Instead use this form:

261

</para>

262

263

264

<command>sudo htpasswd /etc/subversion/password user_name</command>

265

</screen>

266

267

268

<para>This command will prompt you to enter the password. Once you enter the password, the user is added. Now, to access the repository you can run the following command:</para>

269

<screen><command>svn co http://servername/svn</command></screen>

270

271

<para>

272

The password is transmitted as plain text. If you are worried about password snooping, you are advised to use SSL encryption. For details, please refer next section.

273

</para>

274

</warning>

275

</sect3>

276

277

<title>Access via WebDAV protocol with SSL encryption (https://)</title>

278

<para>

279

Accessing Subversion repository via WebDAV protocol with SSL

280

encryption (https://) is similar to http:// except that you

281

must install and configure the digital certificate in your

282

Apache2 web server. To use SSL with Subversion add the above

283

Apache2 configuration to <filename>/etc/apache2/sites-available/default-ssl</filename>.

284

For more information on setting up Apache2 with SSL see <xref linkend="https-configuration"/>.

285

</para>

286

287

<para>

288

You can install a digital certificate issued by a signing

289

authority. Alternatively, you can install your

290

own self-signed certificate.

291

</para>

292

<para>

293

This step assumes you have installed and configured a digital

294

certificate in your Apache 2 web server. Now, to access the

295

Subversion repository, please refer to the above section!

296

The access methods are exactly the same, except the protocol.

297

You must use https:// to access the Subversion repository.

298

</para>

299

300

</sect3>

301

302

<title>Access via custom protocol (svn://)</title>

303

<para>

304

Once the Subversion repository is created, you can configure the

305

access control. You can edit the <filename>

306

/path/to/repos/project/conf/svnserve.conf</filename> file to

307

configure the access control. For example, to set up

308

authentication, you can uncomment the following lines in the

309

configuration file: </para>

310

<programlisting># [general]

311

# password-db = passwd</programlisting>

312

313

<para>

314

After uncommenting the above lines, you can maintain the user

315

list in the passwd file. So, edit the file <filename>passwd

316

</filename> in the same directory and add the new user. The

317

syntax is as follows:

318

</para>

319

<programlisting>username = password</programlisting>

320

<para>

321

For more details, please refer to the file.

322

</para>

323

324

<para>

325

Now, to access Subversion via the svn:// custom protocol, either

326

from the same machine or a different machine, you can run

327

svnserver using svnserve command. The syntax is as follows:

328

</para>

329

<programlisting>$ svnserve -d --foreground -r /path/to/repos

330

# -d -- daemon mode

331

# --foreground -- run in foreground (useful for debugging)

332

# -r -- root of directory to serve

333

334

For more usage details, please refer to:

335

$ svnserve --help</programlisting>

336

337

<para>Once you run this command, Subversion starts listening on default port (3690). To access the project repository, you must run the following command from a terminal prompt: </para>

338

<para>

339

340

<command>svn co svn://hostname/project project --username user_name</command>

341

</screen>

342

</para>

343

<para>Based on server configuration, it prompts for password. Once

344

you are authenticated, it checks out the code from Subversion

345

repository. To synchronize the project repository with the local

346

copy, you can run the <command>update</command> sub-command. The

347

syntax of the command, entered at a terminal prompt, is as follows:

348

</para>

349

<para>

350

351

<command>cd project_dir ; svn update</command>

352

</screen>

353

</para>

354

<para>For more details about using each Subversion sub-command, you

355

can refer to the manual. For example, to learn more about the co

356

(checkout) command, please run the following command from a

357

terminal prompt:</para>

358

359

360

</sect3>

361

362

<title>Access via custom protocol with SSL encryption (svn+ssh://)</title>

363

<para> The configuration and server process is same as in the

364

svn:// method. For details, please refer to the above section.

365

This step assumes you have followed the above step and started

366

the Subversion server using <application>svnserve</application>

367

command.</para>

368

369

<para>It is also assumed that the ssh server is running on that

370

machine and that it is allowing incoming connections. To confirm,

371

please try to login to that machine using ssh. If you can login,

372

everything is perfect. If you cannot login, please address it

373

before continuing further.</para>

374

375

<para>The svn+ssh:// protocol is used to access the Subversion

376

repository using SSL encryption. The data transfer is encrypted

377

using this method. To access the project repository (for example

378

with a checkout), you must use the following command syntax:

379

</para>

380

<para>

381

382

<command>svn co svn+ssh://hostname/var/svn/repos/project</command>

383

</screen>

384

</para>

385

386

<note><para> You must use the full path (/path/to/repos/project)

387

to access the Subversion repository using this access method.

388

</para></note>

389

<para>

390

Based on server configuration, it prompts for password. You must

391

enter the password you use to login via ssh. Once you are

392

authenticated, it checks out the code from the Subversion

393

repository.

394

</para>

395

</sect3>

396

</sect2>

397

</sect1>

398

399

<title>CVS Server</title>

400

<para>

401

CVS is a version control system. You can use it to record the

402

history of source files.

403

</para>

404

405

<title>Installation</title>

406

<para>

407

To install <application>CVS</application>, run the following command from a terminal prompt:

408

409

<command>sudo apt-get install cvs</command>

410

</screen>

411

412

After you install <application>cvs</application>, you should install

413

<application>xinetd</application> to start/stop the cvs server. At the

414

prompt, enter the following command to install

415

<application>xinetd</application>:

416

417

418

<command>sudo apt-get install xinetd</command>

419

</screen>

420

</para>

421

</sect2>

422

423

<title>Configuration</title>

424

<para>

425

Once you install cvs, the repository will be automatically

426

initialized. By default, the repository resides under the

427

<application>/var/lib/cvs</application> directory. You can

428

change this path by running following command:

429

430

431

432

</screen>

433

434

Once the initial repository is set up, you can configure

435

<application>xinetd</application> to start the CVS server.

436

You can copy the following lines to the <filename>

437

/etc/xinetd.d/cvspserver</filename> file.

438

439

440

service cvspserver

441

{

442

port = 2401

443

socket_type = stream

444

protocol = tcp

445

user = root

446

wait = no

447

type = UNLISTED

448

server = /usr/bin/cvs

449

server_args = -f --allow-root /var/lib/cvs pserver

450

disable = no

451

}

452

</programlisting>

453

454

<note>

455

<para>

456

Be sure to edit the repository if you have changed the default

457

repository (<application>/var/lib/cvs</application>) directory.

458

</para>

459

</note>

460

461

Once you have configured <application>xinetd</application> you

462

can start the cvs server by running following command:

463

464

465

<command>sudo /etc/init.d/xinetd restart</command>

466

</screen>

467

</para>

468

<para>

469

You can confirm that the CVS server is running by issuing

470

the following command:

471

</para>

472

473

<para>

474

475

<command>sudo netstat -tap | grep cvs</command>

476

</screen>

477

</para>

478

479

<para>

480

When you run this command, you should see the following line

481

or something similar:

482

</para>

483

484

485

tcp 0 0 *:cvspserver *:* LISTEN

486

</programlisting>

487

488

<para>

489

From here you can continue to add users, add new projects,

490

and manage the CVS server.

491

</para>

492

493

<para>

494

CVS allows the user to add users independently of the

495

underlying OS installation. Probably the easiest way is to use the Linux

496

Users for CVS, although it has potential security issues. Please refer

497

to the CVS manual for details.

498

</para>

499

</warning>

500

501

</sect2>

502

503

<title>Add Projects</title>

504

<para>

505

This section explains how to add new project to the CVS

506

repository. Create the directory and add necessary document

507

and source files to the directory. Now, run the following

508

command to add this project to CVS repository:

509

510

<command>cd your/project</command>

511

<command>cvs -d :pserver:username@hostname.com:/var/lib/cvs import -m "Importing my project to CVS repository" . new_project start</command>

512

</screen>

513

514

<tip>

515

<para>

516

You can use the CVSROOT environment variable to store the CVS root directory.

517

Once you export the CVSROOT environment variable, you can avoid using -d option in the

518

above cvs command.

519

</para>

520

</tip>

521

The string <emphasis>new_project</emphasis> is a vendor

522

tag, and <emphasis>start</emphasis> is a release tag.

523

They serve no purpose in this context, but since CVS requires them, they

524

must be present.

525

526

527

<para>

528

When you add a new project, the CVS user you use must have write access to the

529

CVS repository (<application>/var/lib/cvs</application>). By default, the

530

<application>src</application> group has write access to the CVS

531

repository. So, you can add the user to this group, and he can then add and

532

manage projects in the CVS repository.

533

</para>

534

</warning>

535

</para>

536

</sect2>

537

</sect1>

538

539

<title>References</title>

540

<para><ulink url="http://bazaar-vcs.org/">Bazaar Home Page</ulink></para>

541

<para><ulink url="https://launchpad.net/">Launchpad</ulink></para>

542

<para><ulink url="http://subversion.tigris.org/">Subversion Home Page</ulink></para>

543

<para><ulink url="http://svnbook.red-bean.com/">Subversion Book</ulink></para>

544

<para><ulink

545

url="http://ximbiot.com/cvs/manual/cvs-1.11.21/cvs_toc.html">CVS Manual</ulink></para>

546

<para><ulink url="https://help.ubuntu.com/community/EasyBazaar">Easy Bazaar Ubuntu Wiki page</ulink></para>

547

<para><ulink url="https://help.ubuntu.com/community/Subversion">Ubuntu Wiki Subversion page</ulink></para>

548

</sect1>

549

</chapter>

550

Older »