A GNU Arch Handbook

(start)

Topics are presented in roughly the order they are encountered by a new programmer joining an existing arch-using project.

The GNU Arch project itself is used as a "living example": readers are encouraged to make sure that they have an up-to-date version of this handbook and to learn-by-doing --- trying out the examples on the live GNU project's archives --- as you read.

Part I
Fundamentals

1 Build Your Own tla Binary:
1.1 Why build your own?
1.2 Obtaining Sources
1.3 Other Tools You'll Need or Want
1.4 Configure/Build/Test/Install
1.5 On-line Help

2 Configuring Per-User Parameters:
2.1 Set Your User Identity
2.2 Pick a Default Archive Location
2.3 Pick a Default Mirror Location
2.4 Set Up a Revision Library

3 Registering Remote Archives and Making Local Mirrors
3.1 Coordinates for Upstream Projects
3.2 Registering Archives and Creating Mirrors
3.3 Keeping a Mirror Up to Date

4 Checking Out a Project
4.1 Check Out a Project
4.2 Check Out a Multi-Project Tree
4.3 Examining a Tree's History

5 Starting Your Own Branch
5.1 Create A Personal Archive
5.2 Create a Branch
5.3 Create a Personal Multi-Project Tree
5.4 Examining Your Changes
5.5 Committing Your Changes
5.6 Merging in Changes from Upstream
5.7 Publish Your Archive -- an Outbound Mirror

6 Adding, Deleting, and Renaming Files and Directories
6.1 The Inventory Subsystem
6.2 Naming Convention and Inventory ID Configuration
6.3 Adding a New File or Directory
6.4 Deleting a File or Directory
6.5 Renaming a File or Directory


Part II
Advanced Topics (planned, sorta)


7 Maintaining Your Own Project With Arch
7.1 The Basics: A Star-merge Policy
7.2 A Patch Queue Manager: Why and Roughly How
7.3 Be Strict in What You Transmit...
7.4 Be Tolerant in What You Accept...
7.5 Become an Arch Usage Expert
7.5 Become an Arch Security Expert


8 Archive Integrity and Cryptographic Signing
8.1 Familiarize Yourself With Archive-format Basics!
8.2 Checksums
8.3 The Signing Hook

9 Cherrypicking Merges

10 Hacking Tricks with undo, mkpatch, dopatch, and delta

11 Log Pruning


Part III
Appendices

Appendix A: Arch Terminology and the Global Namespace of Arch Revisions

Appendix B: Highlights from Revision Control Theory