Rev 3338: (Gary Wilson Jr.) core_concepts documentation corrections in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Sun Apr 6 11:13:38 BST 2008
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 3338
revision-id:pqm at pqm.ubuntu.com-20080406101328-z1x7a0hsejxblf39
parent: pqm at pqm.ubuntu.com-20080406083627-bx7vnc0sdjfd2nvs
parent: gary.wilson at gmail.com-20080403052157-hzii4ckr2n6bwxfr
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Sun 2008-04-06 11:13:28 +0100
message:
(Gary Wilson Jr.) core_concepts documentation corrections
modified:
doc/en/user-guide/core_concepts.txt core_concepts.txt-20071114035000-q36a9h57ps06uvnl-2
------------------------------------------------------------
revno: 3299.3.8
revision-id:gary.wilson at gmail.com-20080403052157-hzii4ckr2n6bwxfr
parent: gary.wilson at gmail.com-20080403051759-lpy04q450cmwdykp
committer: Gary Wilson Jr. <gary.wilson at gmail.com>
branch nick: core-concepts-docs
timestamp: Thu 2008-04-03 00:21:57 -0500
message:
Corrected misspelling.
modified:
doc/en/user-guide/core_concepts.txt core_concepts.txt-20071114035000-q36a9h57ps06uvnl-2
------------------------------------------------------------
revno: 3299.3.7
revision-id:gary.wilson at gmail.com-20080403051759-lpy04q450cmwdykp
parent: gary.wilson at gmail.com-20080403051046-qgt8di676t0la57w
committer: Gary Wilson Jr. <gary.wilson at gmail.com>
branch nick: core-concepts-docs
timestamp: Thu 2008-04-03 00:17:59 -0500
message:
Added a comma and capitalized first word of a couple list items.
modified:
doc/en/user-guide/core_concepts.txt core_concepts.txt-20071114035000-q36a9h57ps06uvnl-2
------------------------------------------------------------
revno: 3299.3.6
revision-id:gary.wilson at gmail.com-20080403051046-qgt8di676t0la57w
parent: gary.wilson at gmail.com-20080403050615-r4ue9d3i5ryjsh4m
committer: Gary Wilson Jr. <gary.wilson at gmail.com>
branch nick: core-concepts-docs
timestamp: Thu 2008-04-03 00:10:46 -0500
message:
Removed ending punctuation from simple list.
modified:
doc/en/user-guide/core_concepts.txt core_concepts.txt-20071114035000-q36a9h57ps06uvnl-2
------------------------------------------------------------
revno: 3299.3.5
revision-id:gary.wilson at gmail.com-20080403050615-r4ue9d3i5ryjsh4m
parent: gary.wilson at gmail.com-20080403050413-2ha93u72k778q6y0
committer: Gary Wilson Jr. <gary.wilson at gmail.com>
branch nick: core-concepts-docs
timestamp: Thu 2008-04-03 00:06:15 -0500
message:
Removed trailing whitespace.
modified:
doc/en/user-guide/core_concepts.txt core_concepts.txt-20071114035000-q36a9h57ps06uvnl-2
------------------------------------------------------------
revno: 3299.3.4
revision-id:gary.wilson at gmail.com-20080403050413-2ha93u72k778q6y0
parent: gary.wilson at gmail.com-20080330035843-jg5ry61ax8h0jxy7
parent: pqm at pqm.ubuntu.com-20080403035509-qsxozetmg702c4p0
committer: Gary Wilson Jr. <gary.wilson at gmail.com>
branch nick: core-concepts-docs
timestamp: Thu 2008-04-03 00:04:13 -0500
message:
Merged from bzr.dev.
renamed:
bzrlib/tests/test_revisionnamespaces.py => bzrlib/tests/test_revisionspec.py testrevisionnamespaces.py-20050711050225-8b4af89e6b1efe84
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
bzr bzr.py-20050313053754-5485f144c7006fa6
bzrlib/branch.py branch.py-20050309040759-e4baf4e0d046576e
bzrlib/builtins.py builtins.py-20050830033751-fc01482b9ca23183
bzrlib/bzrdir.py bzrdir.py-20060131065624-156dfea39c4387cb
bzrlib/config.py config.py-20051011043216-070c74f4e9e338e8
bzrlib/doc/api/__init__.py __init__.py-20051224020744-7b87d590843855bc
bzrlib/errors.py errors.py-20050309040759-20512168c4e14fbd
bzrlib/help_topics/__init__.py help_topics.py-20060920210027-rnim90q9e0bwxvy4-1
bzrlib/mail_client.py mail_client.py-20070809192806-vuxt3t19srtpjpdn-1
bzrlib/plugins/launchpad/lp_directory.py lp_indirect.py-20070126012204-de5rugwlt22c7u7e-1
bzrlib/remote.py remote.py-20060720103555-yeeg2x51vn0rbtdp-1
bzrlib/revisionspec.py revisionspec.py-20050907152633-17567659fd5c0ddb
bzrlib/smart/branch.py branch.py-20061124031907-mzh3pla28r83r97f-1
bzrlib/smart/bzrdir.py bzrdir.py-20061122024551-ol0l0o0oofsu9b3t-1
bzrlib/smart/client.py client.py-20061116014825-2k6ada6xgulslami-1
bzrlib/smart/medium.py medium.py-20061103051856-rgu2huy59fkz902q-1
bzrlib/smart/protocol.py protocol.py-20061108035435-ot0lstk2590yqhzr-1
bzrlib/smart/repository.py repository.py-20061128022038-vr5wy5bubyb8xttk-1
bzrlib/smart/request.py request.py-20061108095550-gunadhxmzkdjfeek-1
bzrlib/smart/server.py server.py-20061110062051-chzu10y32vx8gvur-1
bzrlib/smart/vfs.py vfs.py-20061108095550-gunadhxmzkdjfeek-2
bzrlib/status.py status.py-20050505062338-431bfa63ec9b19e6
bzrlib/tests/TestUtil.py TestUtil.py-20050824080200-5f70140a2d938694
bzrlib/tests/__init__.py selftest.py-20050531073622-8d0e3c8845c97a64
bzrlib/tests/blackbox/test_version.py test_version.py-20070312060045-ol7th9z035r3im3d-1
bzrlib/tests/interrepository_implementations/__init__.py __init__.py-20060220054744-baf49a1f88f17b1a
bzrlib/tests/interrepository_implementations/test_interrepository.py test_interrepository.py-20060220061411-1ec13fa99e5e3eee
bzrlib/tests/test_errors.py test_errors.py-20060210110251-41aba2deddf936a8
bzrlib/tests/test_lazy_import.py test_lazy_import.py-20060910203832-f77c54gf3n232za0-2
bzrlib/tests/test_mail_client.py test_mail_client.py-20070809192806-vuxt3t19srtpjpdn-2
bzrlib/tests/test_remote.py test_remote.py-20060720103555-yeeg2x51vn0rbtdp-2
bzrlib/tests/test_selftest.py test_selftest.py-20051202044319-c110a115d8c0456a
bzrlib/tests/test_smart.py test_smart.py-20061122024551-ol0l0o0oofsu9b3t-2
bzrlib/tests/test_smart_transport.py test_ssh_transport.py-20060608202016-c25gvf1ob7ypbus6-2
bzrlib/tests/test_status.py test_status.py-20060516190614-fbf6432e4a6e8aa5
bzrlib/tests/test_transport_implementations.py test_transport_implementations.py-20051227111451-f97c5c7d5c49fce7
bzrlib/tests/test_wsgi.py test_wsgi.py-20061005091552-rz8pva0olkxv0sd8-1
bzrlib/transport/__init__.py transport.py-20050711165921-4978aa7ce1285ad5
bzrlib/transport/chroot.py chroot.py-20061011104729-0us9mgm97z378vnt-1
bzrlib/transport/ftp.py ftp.py-20051116161804-58dc9506548c2a53
bzrlib/transport/http/wsgi.py wsgi.py-20061005091552-rz8pva0olkxv0sd8-2
bzrlib/transport/remote.py ssh.py-20060608202016-c25gvf1ob7ypbus6-1
doc/developers/repository.txt repository.txt-20070709152006-xkhlek456eclha4u-1
doc/en/user-guide/http_smart_server.txt fastcgi.txt-20061005091552-rz8pva0olkxv0sd8-3
bzrlib/tests/test_revisionspec.py testrevisionnamespaces.py-20050711050225-8b4af89e6b1efe84
------------------------------------------------------------
revno: 3299.3.3
revision-id:gary.wilson at gmail.com-20080330035843-jg5ry61ax8h0jxy7
parent: gary.wilson at gmail.com-20080330025829-ueaq6p0tv7f0m39o
committer: Gary Wilson Jr. <gary.wilson at gmail.com>
branch nick: core-concepts-docs
timestamp: Sat 2008-03-29 22:58:43 -0500
message:
Capitalized first word in list items.
modified:
doc/en/user-guide/core_concepts.txt core_concepts.txt-20071114035000-q36a9h57ps06uvnl-2
------------------------------------------------------------
revno: 3299.3.2
revision-id:gary.wilson at gmail.com-20080330025829-ueaq6p0tv7f0m39o
parent: gary.wilson at gmail.com-20080329223649-9fel1068k158ljdf
committer: Gary Wilson Jr. <gary.wilson at gmail.com>
branch nick: core-concepts-docs
timestamp: Sat 2008-03-29 21:58:29 -0500
message:
Several small changes to core_concepts docs:
* Fixed a couple misspellings.
* Several punctuation, capitalization, and grammar fixes.
* Made all bulleted lists use a common indention.
modified:
doc/en/user-guide/core_concepts.txt core_concepts.txt-20071114035000-q36a9h57ps06uvnl-2
------------------------------------------------------------
revno: 3299.3.1
revision-id:gary.wilson at gmail.com-20080329223649-9fel1068k158ljdf
parent: pqm at pqm.ubuntu.com-20080320180614-grrzhydka050ap3a
parent: pqm at pqm.ubuntu.com-20080329121122-edbj8ht3fbr35nfs
committer: Gary Wilson Jr. <gary.wilson at gmail.com>
branch nick: core-concepts-docs
timestamp: Sat 2008-03-29 17:36:49 -0500
message:
Merged upstream changes.
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
bzrlib/_knit_load_data_c.pyx knit_c.pyx-20070509143944-u42gy8w387a10m0j-1
bzrlib/_knit_load_data_py.py _knit_load_data_py.p-20070629000948-9a0nh4s118bi5y8n-1
bzrlib/branch.py branch.py-20050309040759-e4baf4e0d046576e
bzrlib/builtins.py builtins.py-20050830033751-fc01482b9ca23183
bzrlib/bundle/__init__.py changeset.py-20050513021216-b02ab57fb9738913
bzrlib/bundle/serializer/v4.py v10.py-20070611062757-5ggj7k18s9dej0fr-1
bzrlib/bzrdir.py bzrdir.py-20060131065624-156dfea39c4387cb
bzrlib/debug.py debug.py-20061102062349-vdhrw9qdpck8cl35-1
bzrlib/diff.py diff.py-20050309040759-26944fbbf2ebbf36
bzrlib/errors.py errors.py-20050309040759-20512168c4e14fbd
bzrlib/fetch.py fetch.py-20050818234941-26fea6105696365d
bzrlib/help_topics/__init__.py help_topics.py-20060920210027-rnim90q9e0bwxvy4-1
bzrlib/knit.py knit.py-20051212171256-f056ac8f0fbe1bd9
bzrlib/log.py log.py-20050505065812-c40ce11702fe5fb1
bzrlib/mail_client.py mail_client.py-20070809192806-vuxt3t19srtpjpdn-1
bzrlib/merge.py merge.py-20050513021216-953b65a438527106
bzrlib/multiparent.py __init__.py-20070410133617-n1jdhcc1n1mibarp-1
bzrlib/reconcile.py reweave_inventory.py-20051108164726-1e5e0934febac06e
bzrlib/remote.py remote.py-20060720103555-yeeg2x51vn0rbtdp-1
bzrlib/repofmt/knitrepo.py knitrepo.py-20070206081537-pyy4a00xdas0j4pf-1
bzrlib/repofmt/pack_repo.py pack_repo.py-20070813041115-gjv5ma7ktfqwsjgn-1
bzrlib/repofmt/weaverepo.py presplitout.py-20070125045333-wfav3tsh73oxu3zk-1
bzrlib/repository.py rev_storage.py-20051111201905-119e9401e46257e3
bzrlib/revision.py revision.py-20050309040759-e77802c08f3999d5
bzrlib/smart/medium.py medium.py-20061103051856-rgu2huy59fkz902q-1
bzrlib/smart/repository.py repository.py-20061128022038-vr5wy5bubyb8xttk-1
bzrlib/symbol_versioning.py symbol_versioning.py-20060105104851-9ecf8af605d15a80
bzrlib/tests/__init__.py selftest.py-20050531073622-8d0e3c8845c97a64
bzrlib/tests/blackbox/test_pull.py test_pull.py-20051201144907-64959364f629947f
bzrlib/tests/blackbox/test_serve.py test_serve.py-20060913064329-8t2pvmsikl4s3xhl-1
bzrlib/tests/branch_implementations/test_branch.py testbranch.py-20050711070244-121d632bc37d7253
bzrlib/tests/interversionedfile_implementations/test_join.py test_join.py-20060302012326-9b5e9b0f0a03fedc
bzrlib/tests/repository_implementations/test_check_reconcile.py test_broken.py-20070928125406-62236394w0jpbpd6-2
bzrlib/tests/repository_implementations/test_iter_reverse_revision_history.py test_iter_reverse_re-20070217015036-spu7j5ggch7pbpyd-1
bzrlib/tests/repository_implementations/test_reconcile.py test_reconcile.py-20060223022332-572ef70a3288e369
bzrlib/tests/repository_implementations/test_repository.py test_repository.py-20060131092128-ad07f494f5c9d26c
bzrlib/tests/test_bundle.py test.py-20050630184834-092aa401ab9f039c
bzrlib/tests/test_diff.py testdiff.py-20050727164403-d1a3496ebb12e339
bzrlib/tests/test_fetch.py testfetch.py-20050825090644-f73e07e7dfb1765a
bzrlib/tests/test_knit.py test_knit.py-20051212171302-95d4c00dd5f11f2b
bzrlib/tests/test_log.py testlog.py-20050728115707-1a514809d7d49309
bzrlib/tests/test_mail_client.py test_mail_client.py-20070809192806-vuxt3t19srtpjpdn-2
bzrlib/tests/test_osutils.py test_osutils.py-20051201224856-e48ee24c12182989
bzrlib/tests/test_read_bundle.py test_read_bundle.py-20060615211421-ud8cwr1ulgd914zf-1
bzrlib/tests/test_remote.py test_remote.py-20060720103555-yeeg2x51vn0rbtdp-2
bzrlib/tests/test_selftest.py test_selftest.py-20051202044319-c110a115d8c0456a
bzrlib/tests/test_transport_implementations.py test_transport_implementations.py-20051227111451-f97c5c7d5c49fce7
bzrlib/tests/test_versionedfile.py test_versionedfile.py-20060222045249-db45c9ed14a1c2e5
bzrlib/transport/__init__.py transport.py-20050711165921-4978aa7ce1285ad5
bzrlib/transport/http/__init__.py http_transport.py-20050711212304-506c5fd1059ace96
bzrlib/versionedfile.py versionedfile.py-20060222045106-5039c71ee3b65490
bzrlib/weave.py knit.py-20050627021749-759c29984154256b
bzrlib/workingtree.py workingtree.py-20050511021032-29b6ec0a681e02e3
doc/en/user-guide/annotating_changes.txt annotating_changes.t-20071122141511-0knao2lklsdsvb1q-1
doc/en/user-guide/bazaar_workflows.txt bazaar_workflows.txt-20071114035000-q36a9h57ps06uvnl-1
doc/en/user-guide/installing_bazaar.txt installing_bazaar.tx-20071114035000-q36a9h57ps06uvnl-4
doc/en/user-guide/introducing_bazaar.txt introducing_bazaar.t-20071114035000-q36a9h57ps06uvnl-5
doc/en/user-guide/partner_intro.txt partner_workflow.txt-20071122141511-0knao2lklsdsvb1q-4
doc/en/user-guide/undoing_mistakes.txt undoing_mistakes.txt-20071121092300-8fyacngt1w98e5mp-1
=== modified file 'doc/en/user-guide/core_concepts.txt'
--- a/doc/en/user-guide/core_concepts.txt 2008-01-15 20:55:15 +0000
+++ b/doc/en/user-guide/core_concepts.txt 2008-04-03 05:21:57 +0000
@@ -6,49 +6,49 @@
To use Bazaar you need to understand four core concepts:
- * **revision** - a snapshot of the files you're working with
-
- * **working tree** - the directory containing your version controlled
- files and sub-directories
-
- * **branch** - an ordered set of revisions that describe the history of a
- set of files
-
- * **repository** - a store of revisions.
+* **Revision** - a snapshot of the files you're working with.
+
+* **Working tree** - the directory containing your version-controlled
+ files and sub-directories.
+
+* **Branch** - an ordered set of revisions that describe the history of a
+ set of files.
+
+* **Repository** - a store of revisions.
Let's look at each in more detail.
Revision
--------
-A revision is a *snapshot* of the state of a tree of files and directories
+A revision is a *snapshot* of the state of a tree of files and directories,
including their content and shape. A revision also has some metadata
-associated with it including:
-
- * who committed it
- * when it was committed
- * a commit message
- * parent revisions from which it was derived.
-
-Revisions are immutable and can be globally identified uniquely
+associated with it, including:
+
+* Who committed it
+* When it was committed
+* A commit message
+* Parent revisions from which it was derived
+
+Revisions are immutable and can be globally, uniquely identified
by a *revision-id*. An example revision-id is::
pqm at pqm.ubuntu.com-20071129184101-u9506rihe4zbzyyz
-
+
While these identifiers are necessary for internal use and external tool
integration, branch-specific *revision numbers* are the preferred
interface for humans. Typical revision numbers are 1, 42 and 2977.1.59.
See `Specifying revisions`_ in the appendices for a closer look at
the numerous ways that revisions and ranges of revisions can be specified
-in Bazaar, and `Understanding Revision Numbers` for a more details about
-numbering.
+in Bazaar, and `Understanding Revision Numbers`_ for a more detailed
+description of revision numbering.
.. *TODO: add diagram*
Working Tree
------------
-A working tree is a *version controlled directory* holding files the user
+A working tree is a *version-controlled directory* holding files the user
can edit. A working tree is associated with a *branch*.
Many commands use the working tree as their context, e.g. ``commit`` makes
@@ -62,48 +62,45 @@
In the simplest case, a branch is an *ordered series of revisions*.
The last revision is known as the *head*.
-Branches may split apart and be *merged* back together forming a
+Branches may split apart and be *merged* back together, forming a
*graph* of revisions. Technically, the graph shows directed relationships
(between parent and child revisions) and there are no loops, so
you may hear some people refer to it as a *directed acyclic graph* or DAG.
-If this name sound scary, don't worry. The important things
-to remembers are:
-
-* the primary line of development within the DAG is called
- the *mainline*, *trunk* or simply the *left hand side* (LHS)
-
-* a branch might have other lines of development and if it does,
+If this name sounds scary, don't worry. The important things
+to remember are:
+
+* The primary line of development within the DAG is called
+ the *mainline*, *trunk*, or simply the *left hand side* (LHS).
+
+* A branch might have other lines of development and if it does,
these other lines of development begin at some point and end at
another point.
-If you understand that, you understand branches.
-
.. *TODO: add diagram*
Repository
----------
-A repository is simply a *store of revisions*. In the simpliest case,
+A repository is simply a *store of revisions*. In the simplest case,
each branch has its own repository. In other cases, it makes sense for
branches to share a repository in order to optimize disk usage.
.. *TODO: add diagram*
-
Putting the concepts together
-----------------------------
-Once the concepts above are understood, the various ways of using Bazaar
-are easier to understand. The simpliest way of using Bazaar is to use
-a *standalone tree* which has a working tree, branch and repository
+Once you have grasped the concepts above, the various ways of using Bazaar
+should become easier to understand. The simplest way of using Bazaar is
+to use a *standalone tree*, which has a working tree, branch, and repository
all in a single location. Other common scenarios include:
- * *shared repositories* - working tree and branch are collocated
- but the repository is in a higher level directory
-
- * *lightweight checkouts* - branch is stored is a different location
- to the working tree.
-
-The best way to use Bazaar depends on what you want to do so let's look
-at some common workflows next.
+* *Shared repositories* - working tree and branch are colocated, but the
+ repository is in a higher level directory.
+
+* *Lightweight checkouts* - branch is stored is a different location
+ to the working tree.
+
+The best way to use Bazaar, however, depends on your needs. Let's take a
+look at some common workflows next.
More information about the bazaar-commits
mailing list