2977.1.1
by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2 |
1 |
Core concepts |
2 |
============= |
|
3 |
||
4 |
A simple user model |
|
5 |
------------------- |
|
6 |
||
3074.1.1
by Ian Clatworthy
feedback from mrevell |
7 |
To use Bazaar you need to understand four core concepts: |
8 |
||
3299.3.3
by Gary Wilson Jr.
Capitalized first word in list items. |
9 |
* **Revision** - a snapshot of the files you're working with. |
3299.3.2
by Gary Wilson Jr.
Several small changes to core_concepts docs: |
10 |
|
3299.3.3
by Gary Wilson Jr.
Capitalized first word in list items. |
11 |
* **Working tree** - the directory containing your version-controlled |
3299.3.2
by Gary Wilson Jr.
Several small changes to core_concepts docs: |
12 |
files and sub-directories. |
13 |
||
3299.3.3
by Gary Wilson Jr.
Capitalized first word in list items. |
14 |
* **Branch** - an ordered set of revisions that describe the history of a |
3299.3.2
by Gary Wilson Jr.
Several small changes to core_concepts docs: |
15 |
set of files. |
16 |
||
3299.3.3
by Gary Wilson Jr.
Capitalized first word in list items. |
17 |
* **Repository** - a store of revisions. |
3074.1.1
by Ian Clatworthy
feedback from mrevell |
18 |
|
19 |
Let's look at each in more detail. |
|
2977.1.1
by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2 |
20 |
|
21 |
Revision |
|
22 |
-------- |
|
23 |
||
3299.3.2
by Gary Wilson Jr.
Several small changes to core_concepts docs: |
24 |
A revision is a *snapshot* of the state of a tree of files and directories, |
2977.1.1
by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2 |
25 |
including their content and shape. A revision also has some metadata |
3299.3.2
by Gary Wilson Jr.
Several small changes to core_concepts docs: |
26 |
associated with it, including: |
27 |
||
3299.3.6
by Gary Wilson Jr.
Removed ending punctuation from simple list. |
28 |
* Who committed it |
29 |
* When it was committed |
|
30 |
* A commit message |
|
31 |
* Parent revisions from which it was derived |
|
3299.3.2
by Gary Wilson Jr.
Several small changes to core_concepts docs: |
32 |
|
33 |
Revisions are immutable and can be globally, uniquely identified |
|
2977.1.17
by Ian Clatworthy
more chapter 1 tweaks |
34 |
by a *revision-id*. An example revision-id is:: |
35 |
||
36 |
pqm@pqm.ubuntu.com-20071129184101-u9506rihe4zbzyyz |
|
3299.3.5
by Gary Wilson Jr.
Removed trailing whitespace. |
37 |
|
3412.1.3
by Ian Clatworthy
improve rev number explanation using Robert's text |
38 |
Revision-ids are generated at commit time or, for imports from other |
39 |
systems, at the time of import. While revision-ids are necessary |
|
40 |
for internal use and external tool integration, branch-specific |
|
41 |
*revision numbers* are the preferred interface for humans. |
|
42 |
||
43 |
Revision numbers are dotted decimal identifiers like 1, 42 and 2977.1.59 |
|
44 |
that trace a path through the revision number graph for a branch. |
|
45 |
Revision numbers are generally shorter than revision-ids and, |
|
46 |
within a single branch, can be compared with each other to get a sense |
|
47 |
of their relationship. For example, revision 10 is the mainline (see below) |
|
48 |
revision immediately after revision 9. Revision numbers |
|
49 |
are generated on the fly when commands are executing, because they |
|
50 |
depend on which revision is the tip (i.e. most recent revision) |
|
51 |
in the branch. |
|
52 |
||
4634.39.41
by Ian Clatworthy
Fix the broken links in the User Guide |
53 |
See `Specifying revisions <specifying_revisions.html>`_ in the appendices |
54 |
for a closer look at the numerous ways that revisions and ranges of |
|
55 |
revisions can be specified in Bazaar, and `Understanding Revision Numbers |
|
56 |
<zen.html#understanding-revision-numbers>`_ for a more detailed |
|
3299.3.2
by Gary Wilson Jr.
Several small changes to core_concepts docs: |
57 |
description of revision numbering. |
2977.1.1
by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2 |
58 |
|
2977.1.9
by Ian Clatworthy
first cut at Distributed collaboration chapter |
59 |
.. *TODO: add diagram* |
2977.1.1
by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2 |
60 |
|
61 |
Working Tree |
|
62 |
------------ |
|
63 |
||
3299.3.2
by Gary Wilson Jr.
Several small changes to core_concepts docs: |
64 |
A working tree is a *version-controlled directory* holding files the user |
2977.1.1
by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2 |
65 |
can edit. A working tree is associated with a *branch*. |
66 |
||
67 |
Many commands use the working tree as their context, e.g. ``commit`` makes |
|
68 |
a new revision using the current content of files in the working tree. |
|
69 |
||
2977.1.9
by Ian Clatworthy
first cut at Distributed collaboration chapter |
70 |
.. *TODO: add diagram* |
2977.1.1
by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2 |
71 |
|
72 |
Branch |
|
73 |
------ |
|
74 |
||
75 |
In the simplest case, a branch is an *ordered series of revisions*. |
|
3412.1.3
by Ian Clatworthy
improve rev number explanation using Robert's text |
76 |
The last revision is known as the *tip*. |
2977.1.1
by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2 |
77 |
|
3299.3.2
by Gary Wilson Jr.
Several small changes to core_concepts docs: |
78 |
Branches may split apart and be *merged* back together, forming a |
3074.1.1
by Ian Clatworthy
feedback from mrevell |
79 |
*graph* of revisions. Technically, the graph shows directed relationships |
80 |
(between parent and child revisions) and there are no loops, so |
|
81 |
you may hear some people refer to it as a *directed acyclic graph* or DAG. |
|
82 |
||
3299.3.2
by Gary Wilson Jr.
Several small changes to core_concepts docs: |
83 |
If this name sounds scary, don't worry. The important things |
84 |
to remember are: |
|
85 |
||
86 |
* The primary line of development within the DAG is called |
|
3299.3.7
by Gary Wilson Jr.
Added a comma and capitalized first word of a couple list items. |
87 |
the *mainline*, *trunk*, or simply the *left hand side* (LHS). |
3299.3.2
by Gary Wilson Jr.
Several small changes to core_concepts docs: |
88 |
|
89 |
* A branch might have other lines of development and if it does, |
|
3074.1.1
by Ian Clatworthy
feedback from mrevell |
90 |
these other lines of development begin at some point and end at |
91 |
another point. |
|
92 |
||
2977.1.9
by Ian Clatworthy
first cut at Distributed collaboration chapter |
93 |
.. *TODO: add diagram* |
2977.1.1
by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2 |
94 |
|
95 |
Repository |
|
96 |
---------- |
|
97 |
||
3299.3.2
by Gary Wilson Jr.
Several small changes to core_concepts docs: |
98 |
A repository is simply a *store of revisions*. In the simplest case, |
2977.1.1
by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2 |
99 |
each branch has its own repository. In other cases, it makes sense for |
100 |
branches to share a repository in order to optimize disk usage. |
|
101 |
||
2977.1.9
by Ian Clatworthy
first cut at Distributed collaboration chapter |
102 |
.. *TODO: add diagram* |
2977.1.1
by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2 |
103 |
|
104 |
Putting the concepts together |
|
105 |
----------------------------- |
|
106 |
||
3299.3.2
by Gary Wilson Jr.
Several small changes to core_concepts docs: |
107 |
Once you have grasped the concepts above, the various ways of using Bazaar |
108 |
should become easier to understand. The simplest way of using Bazaar is |
|
109 |
to use a *standalone tree*, which has a working tree, branch, and repository |
|
2977.1.1
by Ian Clatworthy
First cut at new look User Guide including chapters 1 and 2 |
110 |
all in a single location. Other common scenarios include: |
111 |
||
4634.39.41
by Ian Clatworthy
Fix the broken links in the User Guide |
112 |
* `Shared repositories <branching_a_project.html#a-reminder-about-shared-repositories>`_ |
113 |
- working tree and branch are colocated, but the repository is in a higher level |
|
3779.2.1
by mernst at mit
Improved documentation of stacked and lightweight branches |
114 |
directory. |
115 |
||
4634.39.41
by Ian Clatworthy
Fix the broken links in the User Guide |
116 |
* `Stacked branches <stacked.html>`_ - branch stores just its |
3779.2.1
by mernst at mit
Improved documentation of stacked and lightweight branches |
117 |
unique revisions, using its parent's repository for common revisions. |
118 |
||
4634.39.41
by Ian Clatworthy
Fix the broken links in the User Guide |
119 |
* `Lightweight checkouts <using_checkouts.html#getting-a-lightweight-checkout>`_ |
120 |
- branch is stored in a different location to the working tree. |
|
3299.3.2
by Gary Wilson Jr.
Several small changes to core_concepts docs: |
121 |
|
122 |
The best way to use Bazaar, however, depends on your needs. Let's take a |
|
123 |
look at some common workflows next. |