Rev 3345: (beuno) guide to integrating with bzrlib in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Tue Apr 8 13:41:43 BST 2008
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 3345
revision-id:pqm at pqm.ubuntu.com-20080408124131-ar7bjhzp6bzggv8m
parent: pqm at pqm.ubuntu.com-20080407100447-bsfwxwxhe0mcbp7q
parent: mbp at sourcefrog.net-20080408105541-cec8p2022jye422i
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Tue 2008-04-08 13:41:31 +0100
message:
(beuno) guide to integrating with bzrlib
added:
doc/developers/integration.txt integration.txt-20080404022341-2lorxocp1in07zij-1
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
doc/developers/index.txt index.txt-20070508041241-qznziunkg0nffhiw-1
------------------------------------------------------------
revno: 3344.1.2
revision-id:mbp at sourcefrog.net-20080408105541-cec8p2022jye422i
parent: mbp at sourcefrog.net-20080408074655-axjno8luuqrrbv1m
committer: Martin Pool <mbp at sourcefrog.net>
branch nick: doc
timestamp: Tue 2008-04-08 20:55:41 +1000
message:
Fix ReST syntax in integration guide
modified:
doc/developers/integration.txt integration.txt-20080404022341-2lorxocp1in07zij-1
------------------------------------------------------------
revno: 3344.1.1
revision-id:mbp at sourcefrog.net-20080408074655-axjno8luuqrrbv1m
parent: pqm at pqm.ubuntu.com-20080407100447-bsfwxwxhe0mcbp7q
parent: argentina at gmail.com-20080406055452-uepzp05mp4smsjm9
committer: Martin Pool <mbp at sourcefrog.net>
branch nick: doc
timestamp: Tue 2008-04-08 17:46:55 +1000
message:
Merge guide to integrating with bzrlib
added:
doc/developers/integration.txt integration.txt-20080404022341-2lorxocp1in07zij-1
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
doc/developers/index.txt index.txt-20070508041241-qznziunkg0nffhiw-1
------------------------------------------------------------
revno: 3250.4.6
revision-id:argentina at gmail.com-20080406055452-uepzp05mp4smsjm9
parent: argentina at gmail.com-20080406014104-4mbd7ybv2no50ndw
committer: Martin Albisetti <argentina at gmail.com>
branch nick: bzr.docs
timestamp: Sun 2008-04-06 02:54:52 -0300
message:
Added changes sent by Aaron Bently
modified:
doc/developers/integration.txt integration.txt-20080404022341-2lorxocp1in07zij-1
------------------------------------------------------------
revno: 3250.4.5
revision-id:argentina at gmail.com-20080406014104-4mbd7ybv2no50ndw
parent: argentina at gmail.com-20080405161656-6py5w43fp8v7pqmv
committer: Martin Albisetti <argentina at gmail.com>
branch nick: bzr.docs
timestamp: Sat 2008-04-05 22:41:04 -0300
message:
Removed trailing whitespaces
modified:
doc/developers/integration.txt integration.txt-20080404022341-2lorxocp1in07zij-1
------------------------------------------------------------
revno: 3250.4.4
revision-id:argentina at gmail.com-20080405161656-6py5w43fp8v7pqmv
parent: argentina at gmail.com-20080404024343-rosvqm8e1m5ra57z
committer: Martin Albisetti <argentina at gmail.com>
branch nick: bzr.docs
timestamp: Sat 2008-04-05 13:16:56 -0300
message:
Shortened to under 80 characters per line, and removed all wiki-specific information
modified:
doc/developers/integration.txt integration.txt-20080404022341-2lorxocp1in07zij-1
------------------------------------------------------------
revno: 3250.4.3
revision-id:argentina at gmail.com-20080404024343-rosvqm8e1m5ra57z
parent: argentina at gmail.com-20080404022539-oo46zal2ncolz9d7
committer: Martin Albisetti <argentina at gmail.com>
branch nick: bzr.docs
timestamp: Thu 2008-04-03 23:43:43 -0300
message:
Added the documentation addition to NEWS
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
------------------------------------------------------------
revno: 3250.4.2
revision-id:argentina at gmail.com-20080404022539-oo46zal2ncolz9d7
parent: argentina at gmail.com-20080404022520-f37c005qaftt93m9
parent: pqm at pqm.ubuntu.com-20080403080121-tbx3clqp8wqe776c
committer: Martin Albisetti <argentina at gmail.com>
branch nick: bzr.docs
timestamp: Thu 2008-04-03 23:25:39 -0300
message:
Merge from bzr.dev
added:
bzrlib/directory_service.py directory_service.py-20080305221044-vr2mkvlsk8jypa2y-1
bzrlib/tests/blackbox/test_hooks.py test_hooks.py-20080308163236-xljgf9j41hik1x21-1
bzrlib/tests/test_directory_service.py test_directory_servi-20080305221044-vr2mkvlsk8jypa2y-2
bzrlib/tests/test_uncommit.py test_uncommit.py-20080316104338-y3gxu67g5m2qih10-1
bzrlib/tests/tree_implementations/test_annotate_iter.py test_annotate_iter.p-20080315092519-h4dc43rntmfmq16d-1
bzrlib/transport/nosmart.py nosmart.py-20080402095843-6ib17idympwy1zkr-1
doc/en/admin-guide/ docenadminguide-20080305135054-y7y2c986yf94zljn-1
doc/en/admin-guide/index.txt index.txt-20080305140741-ecw0lap8dxkxc05g-1
renamed:
bzrlib/plugins/launchpad/lp_indirect.py => bzrlib/plugins/launchpad/lp_directory.py lp_indirect.py-20070126012204-de5rugwlt22c7u7e-1
bzrlib/plugins/launchpad/test_lp_indirect.py => bzrlib/plugins/launchpad/test_lp_directory.py test_lp_indirect.py-20070126002743-oyle362tzv9cd8mi-1
bzrlib/tests/test_revisionnamespaces.py => bzrlib/tests/test_revisionspec.py testrevisionnamespaces.py-20050711050225-8b4af89e6b1efe84
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
README README-20050309040720-8f368abf9f346b9d
bzr bzr.py-20050313053754-5485f144c7006fa6
bzrlib/__init__.py __init__.py-20050309040759-33e65acf91bbcd5d
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/annotate.py annotate.py-20050922133147-7c60541d2614f022
bzrlib/branch.py branch.py-20050309040759-e4baf4e0d046576e
bzrlib/bugtracker.py bugtracker.py-20070410073305-vu1vu1qosjurg8kb-1
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/config.py config.py-20051011043216-070c74f4e9e338e8
bzrlib/debug.py debug.py-20061102062349-vdhrw9qdpck8cl35-1
bzrlib/delta.py delta.py-20050729221636-54cf14ef94783d0a
bzrlib/deprecated_graph.py graph.py-20050905070950-b47dce53236c5e48
bzrlib/diff.py diff.py-20050309040759-26944fbbf2ebbf36
bzrlib/dirstate.py dirstate.py-20060728012006-d6mvoihjb3je9peu-1
bzrlib/doc/api/__init__.py __init__.py-20051224020744-7b87d590843855bc
bzrlib/errors.py errors.py-20050309040759-20512168c4e14fbd
bzrlib/fetch.py fetch.py-20050818234941-26fea6105696365d
bzrlib/graph.py graph_walker.py-20070525030359-y852guab65d4wtn0-1
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/merge3.py merge3.py-20050704130834-bf0597094828a2e1
bzrlib/merge_directive.py merge_directive.py-20070228184838-ja62280spt1g7f4x-1
bzrlib/missing.py missing.py-20050812153334-097f7097e2a8bcd1
bzrlib/multiparent.py __init__.py-20070410133617-n1jdhcc1n1mibarp-1
bzrlib/plugin.py plugin.py-20050622060424-829b654519533d69
bzrlib/plugins/launchpad/__init__.py __init__.py-20060315182712-2d5feebd2a1032dc
bzrlib/plugins/launchpad/lp_registration.py lp_registration.py-20060315190948-daa617eafe3a8d48
bzrlib/reconcile.py reweave_inventory.py-20051108164726-1e5e0934febac06e
bzrlib/registry.py lazy_factory.py-20060809213415-2gfvqadtvdn0phtg-1
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/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/symbol_versioning.py symbol_versioning.py-20060105104851-9ecf8af605d15a80
bzrlib/tests/TestUtil.py TestUtil.py-20050824080200-5f70140a2d938694
bzrlib/tests/__init__.py selftest.py-20050531073622-8d0e3c8845c97a64
bzrlib/tests/blackbox/__init__.py __init__.py-20051128053524-eba30d8255e08dc3
bzrlib/tests/blackbox/test_merge.py test_merge.py-20060323225809-9bc0459c19917f41
bzrlib/tests/blackbox/test_mv.py test_mv.py-20060705114902-33tkxz0o9cdshemo-1
bzrlib/tests/blackbox/test_pull.py test_pull.py-20051201144907-64959364f629947f
bzrlib/tests/blackbox/test_push.py test_push.py-20060329002750-929af230d5d22663
bzrlib/tests/blackbox/test_send.py test_bundle.py-20060616222707-c21c8b7ea5ef57b1
bzrlib/tests/blackbox/test_serve.py test_serve.py-20060913064329-8t2pvmsikl4s3xhl-1
bzrlib/tests/blackbox/test_uncommit.py test_uncommit.py-20051027212835-84944b63adae51be
bzrlib/tests/blackbox/test_upgrade.py test_upgrade.py-20060120060132-b41e5ed2f886ad28
bzrlib/tests/blackbox/test_version.py test_version.py-20070312060045-ol7th9z035r3im3d-1
bzrlib/tests/branch_implementations/test_branch.py testbranch.py-20050711070244-121d632bc37d7253
bzrlib/tests/branch_implementations/test_revision_history.py test_revision_histor-20070326062311-v7co92liyuchb80w-1
bzrlib/tests/bzrdir_implementations/test_bzrdir.py test_bzrdir.py-20060131065642-0ebeca5e30e30866
bzrlib/tests/interrepository_implementations/__init__.py __init__.py-20060220054744-baf49a1f88f17b1a
bzrlib/tests/interrepository_implementations/test_interrepository.py test_interrepository.py-20060220061411-1ec13fa99e5e3eee
bzrlib/tests/intertree_implementations/test_compare.py test_compare.py-20060724101752-09ysswo1a92uqyoz-2
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_annotate.py test_annotate.py-20061213215015-sttc9agsxomls7q0-1
bzrlib/tests/test_bugtracker.py test_bugtracker.py-20070410073305-vu1vu1qosjurg8kb-2
bzrlib/tests/test_bundle.py test.py-20050630184834-092aa401ab9f039c
bzrlib/tests/test_commit.py test_commit.py-20050914060732-279f057f8c295434
bzrlib/tests/test_diff.py testdiff.py-20050727164403-d1a3496ebb12e339
bzrlib/tests/test_errors.py test_errors.py-20060210110251-41aba2deddf936a8
bzrlib/tests/test_fetch.py testfetch.py-20050825090644-f73e07e7dfb1765a
bzrlib/tests/test_graph.py test_graph_walker.py-20070525030405-enq4r60hhi9xrujc-1
bzrlib/tests/test_knit.py test_knit.py-20051212171302-95d4c00dd5f11f2b
bzrlib/tests/test_lazy_import.py test_lazy_import.py-20060910203832-f77c54gf3n232za0-2
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_merge.py testmerge.py-20050905070950-c1b5aa49ff911024
bzrlib/tests/test_merge3.py merge3.py-20050704130834-556689114c89e6f2
bzrlib/tests/test_merge_directive.py test_merge_directive-20070228184838-ja62280spt1g7f4x-2
bzrlib/tests/test_osutils.py test_osutils.py-20051201224856-e48ee24c12182989
bzrlib/tests/test_plugins.py plugins.py-20050622075746-32002b55e5e943e9
bzrlib/tests/test_read_bundle.py test_read_bundle.py-20060615211421-ud8cwr1ulgd914zf-1
bzrlib/tests/test_registry.py test_lazy_factory.py-20060809213415-2gfvqadtvdn0phtg-2
bzrlib/tests/test_remote.py test_remote.py-20060720103555-yeeg2x51vn0rbtdp-2
bzrlib/tests/test_revision.py testrevision.py-20050804210559-46f5e1eb67b01289
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_transform.py test_transaction.py-20060105172520-b3ffb3946550e6c4
bzrlib/tests/test_transport_implementations.py test_transport_implementations.py-20051227111451-f97c5c7d5c49fce7
bzrlib/tests/test_tsort.py testtsort.py-20051025073946-27da871c394d5be4
bzrlib/tests/test_upgrade.py test_upgrade.py-20051004040251-555fe1d2bae1bc71
bzrlib/tests/test_urlutils.py test_urlutils.py-20060502192900-46b1f9579987cf9c
bzrlib/tests/test_versionedfile.py test_versionedfile.py-20060222045249-db45c9ed14a1c2e5
bzrlib/tests/test_workingtree_4.py test_workingtree_4.p-20070223025758-531n3tznl3zacv2o-1
bzrlib/tests/test_wsgi.py test_wsgi.py-20061005091552-rz8pva0olkxv0sd8-1
bzrlib/tests/tree_implementations/__init__.py __init__.py-20060717075546-420s7b0bj9hzeowi-2
bzrlib/tests/workingtree_implementations/test_locking.py test_locking.py-20060707151933-tav3o2hpibwi53u4-3
bzrlib/tests/workingtree_implementations/test_merge_from_branch.py test_merge_from_bran-20060904034200-12jxyk2zlhpufxe1-1
bzrlib/tests/workingtree_implementations/test_parents.py test_set_parents.py-20060807231740-yicmnlci1mj8smu1-1
bzrlib/trace.py trace.py-20050309040759-c8ed824bdcd4748a
bzrlib/transform.py transform.py-20060105172343-dd99e54394d91687
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/__init__.py http_transport.py-20050711212304-506c5fd1059ace96
bzrlib/transport/http/_urllib.py _urlgrabber.py-20060113083826-0bbf7d992fbf090c
bzrlib/transport/http/_urllib2_wrappers.py _urllib2_wrappers.py-20060913231729-ha9ugi48ktx481ao-1
bzrlib/transport/http/wsgi.py wsgi.py-20061005091552-rz8pva0olkxv0sd8-2
bzrlib/transport/remote.py ssh.py-20060608202016-c25gvf1ob7ypbus6-1
bzrlib/tree.py tree.py-20050309040759-9d5f2496be663e77
bzrlib/tsort.py tsort.py-20051025073946-7808f6aaf7d07208
bzrlib/ui/__init__.py ui.py-20050824083933-8cf663c763ba53a9
bzrlib/uncommit.py uncommit.py-20050626215513-5ec509fa425b305c
bzrlib/upgrade.py history2weaves.py-20050818063535-e7d319791c19a8b2
bzrlib/urlutils.py urlutils.py-20060502195429-e8a161ecf8fac004
bzrlib/util/configobj/configobj.py configobj.py-20051018184548-06992a2246425e3e
bzrlib/util/configobj/docs/configobj.txt configobj.txt-20051018184548-4949b5f17e6a19c7
bzrlib/util/configobj/docs/validate.txt validate.txt-20051018184548-9e0e5ad913e258f5
bzrlib/version.py version.py-20060816024207-ves6ult9a11taj9t-1
bzrlib/versionedfile.py versionedfile.py-20060222045106-5039c71ee3b65490
bzrlib/weave.py knit.py-20050627021749-759c29984154256b
bzrlib/workingtree.py workingtree.py-20050511021032-29b6ec0a681e02e3
bzrlib/workingtree_4.py workingtree_4.py-20070208044105-5fgpc5j3ljlh5q6c-1
doc/developers/lca-merge.txt lcamerge.txt-20080103061803-9isydn4ivgwrvorw-1
doc/developers/repository.txt repository.txt-20070709152006-xkhlek456eclha4u-1
doc/en/mini-tutorial/index.txt index.txt-20070813141352-2u64ooqzo0or4hss-2
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/hooks.txt hooks.txt-20070829200551-7nr6e5a1io6x78uf-1
doc/en/user-guide/http_smart_server.txt fastcgi.txt-20061005091552-rz8pva0olkxv0sd8-3
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/resolving_conflicts.txt resolving_conflicts.-20071122141511-0knao2lklsdsvb1q-5
doc/en/user-guide/undoing_mistakes.txt undoing_mistakes.txt-20071121092300-8fyacngt1w98e5mp-1
doc/en/user-guide/version_info.txt version_info.txt-20060921215543-gju6o5xdic8w25np-1
setup.py setup.py-20050314065409-02f8a0a6e3f9bc70
bzrlib/plugins/launchpad/lp_directory.py lp_indirect.py-20070126012204-de5rugwlt22c7u7e-1
bzrlib/plugins/launchpad/test_lp_directory.py test_lp_indirect.py-20070126002743-oyle362tzv9cd8mi-1
bzrlib/tests/test_revisionspec.py testrevisionnamespaces.py-20050711050225-8b4af89e6b1efe84
------------------------------------------------------------
revno: 3250.4.1
revision-id:argentina at gmail.com-20080404022520-f37c005qaftt93m9
parent: pqm at pqm.ubuntu.com-20080304113936-4wrordr8lrxhvfdl
committer: Martin Albisetti <argentina at gmail.com>
branch nick: bzr.docs
timestamp: Thu 2008-04-03 23:25:20 -0300
message:
Added integration guide for developers
added:
doc/developers/integration.txt integration.txt-20080404022341-2lorxocp1in07zij-1
modified:
doc/developers/index.txt index.txt-20070508041241-qznziunkg0nffhiw-1
=== added file 'doc/developers/integration.txt'
--- a/doc/developers/integration.txt 1970-01-01 00:00:00 +0000
+++ b/doc/developers/integration.txt 2008-04-08 10:55:41 +0000
@@ -0,0 +1,304 @@
+=======================
+Integrating with Bazaar
+=======================
+
+This page should hopefully become a quick guide to integrating other
+(Python-based) software with Bazaar.
+
+Manipulating the Working Tree
+=============================
+Most objects in Bazaar are in files, named after the class they contain.
+To manipulate the Working Tree we need a valid WorkingTree object, which
+is loaded from the workingtree.py file, eg::
+
+ from bzrlib import workingtree
+ wt = workingtree.WorkingTree.open('/home/jebw/bzrtest')
+
+
+This gives us a WorkingTree object, which has various methods spread over
+itself, and its parent classes MutableTree and Tree - its worth having a
+look through these three files (workingtree.py, mutabletree.py and tree.py)
+to see which methods are available.
+
+Compare trees
+===============
+There are two methods for comparing trees: ``changes_from`` and
+``iter_changes``. ``iter_changes`` is more regular and precise, but it is
+somewhat harder to work with. See the API documentation for more details.
+
+``changes_from`` creates a Delta object showing changes::
+
+ from bzrlib import delta
+ changes = wt.changes_from(wt.basis_tree())
+
+This gives us a Delta object, which has several lists of files for each type of
+change, eg changes.added is a list of added files, changes.removed is list
+of removed files, changes.modified is a list of modified files. The contents
+of the lists aren't just filenames, but include other information as well.
+To grab just the filename we want the first value, eg::
+
+ print("list of newly added files")
+ for filename in changes.added:
+ print("%s has been added" % filename[0])
+
+
+The exception to this is changes.renamed, where the list returned for each
+renamed files contains both the old and new names -- one or both may interest
+you, depending on what you're doing.
+
+For example::
+
+ print("list of renamed files")
+ for filename in changes.renamed:
+ print("%s has been renamed to %s" % (filename[0], filename[1]))
+
+
+Adding Files
+============
+
+If you want to add files the same way ``bzr add`` does, you can use
+MutableTree.smart_add. By default, this is recursive. Paths can either be
+absolute or relative to the workingtree::
+
+ wt.smart_add(['dir1/filea.txt', 'fileb.txt',
+ '/home/jebw/bzrtesttree/filec.txt'])
+
+
+For more precise control over which files to add, use MutableTree.add::
+
+ wt.add(['dir1/filea.txt', 'fileb.txt', '/home/jebw/bzrtesttree/filec.txt'])
+
+
+Removing Files
+==============
+
+You can remove multiple files at once. The file paths need to be relative
+to the workingtree::
+
+ wt.remove(['filea.txt', 'fileb.txt', 'dir1'])
+
+
+By default, the files are not deleted, just removed from the inventory.
+To delete them from the filesystem as well::
+
+ wt.remove(['filea.txt', 'fileb.txt', 'dir1'], keep_files=False)
+
+
+Renaming a File
+===============
+
+You can rename one file to a different name using WorkingTree.rename_one.
+You just provide the old and new names, eg::
+
+ wt.rename_one('oldfile.txt','newfile.txt')
+
+
+Moving Files
+============
+
+You can move multiple files from one directory into another using
+WorkingTree.move::
+
+ wt.move(['olddir/file.txt'], 'newdir')
+
+
+More complicated renames/moves can be done with transform.TreeTransform,
+which is outside the scope of this document.
+
+
+Committing Changes
+==================
+
+To commit _all_ the changes to our working tree we can just call the
+WorkingTree's commit method, giving it a commit message, eg::
+
+ wt.commit('this is my commit message')
+
+
+To commit only certain files, we need to provide a list of filenames which we
+want committing, eg::
+
+ wt.commit(message='this is my commit message', specific_files=['fileA.txt',
+ 'dir2/fileB.txt', 'fileD.txt'])
+
+
+Generating a Log for a File
+===========================
+
+Generating a log is, in itself, simple. Grab a branch (see below) and pass
+it to show_log together with a log formatter, eg::
+
+ from bzrlib import log
+ from bzrlib import branch
+
+ b = branch.Branch.open('/path/to/bazaar/branch')
+ lf = log.LongLogFormatter(to_file=sys.stdout)
+ log.show_log(b, lf)
+
+
+Three log formatters are included with bzrlib: LongLogFormatter,
+ShortLogFormatter and LineLogFormatter. These provide long, short and
+single-line log output formats. It's also possible to write your own in
+very little code.
+
+Annotating a File
+=================
+
+To annotate a file, we want to walk every line of a file, retrieving the
+revision which last modified/created that line and then retrieving the
+information for that revision.
+
+First we get an annotation iterator for the file we are interested in::
+
+ tree, relpath = workingtree.WorkingTree.open_containing('/path/to/file.txt')
+ fileid = tree.path2id(relpath)
+ annotation = list(tree.annotate_iter(fileid))
+
+
+To avoid repeatedly retrieving the same revisions we grab all revisions
+associated with the file at once and build up a map of id to revision
+information. We also build an map of revision numbers, again indexed
+by the revision id::
+
+ revision_ids = set(revision_id for revision_id, text in annotation)
+ revisions = tree.branch.repository.get_revisions(revision_ids)
+ revision_map = dict(izip(revision_ids, revisions))
+ revno_map = tree.branch.get_revision_id_to_revno_map()
+
+
+Finally, we use our annotation iterator to walk the lines of the file,
+displaying the information from our revision maps as we go::
+
+ for revision_id, text in annotation :
+ rev = revision_map[revision_id]
+ revno = revno_map[revision_id]
+ revno_string = '.'.join(str(i) for i in revno)
+ print "%s, %s: %s" % (revno_string, rev.committer, text)
+
+
+Working with branches
+=====================
+
+To work with a branch you need a branch object, created from your branch::
+
+ from bzrlib import branch
+
+ b = branch.Branch.open('/home/jebw/bzrtest')
+
+
+Branching from an existing branch
+=================================
+
+To branch you create a branch object representing the branch you are
+branching from, and supply a path/url to the new branch location.
+The following code clones the bzr.dev branch (the latest copy of the Bazaar
+source code) - be warned it has to download 60meg so takes a while to run
+with no feedback::
+
+ from bzrlib import branch
+
+ b = branch.Branch.open('http://bazaar-vcs.org/bzr/bzr.dev')
+ nb = b.bzrdir.sprout('/tmp/newBzrBranch').open_branch()
+
+
+This provides no feedback, since Bazaar automatically uses the 'silent' UI.
+
+
+Pushing and pulling branches
+============================
+
+To push a branch you need to open the source and destination branches, then
+just call push with the other branch as a parameter::
+
+ from bzrlib import branch
+
+ b1 = branch.Branch.open('file:///home/user/mybranch')
+ b2 = branch.Branch.open('http://bazaar-vcs.org/bzr/bzr.dev')
+ b1.push(b2)
+
+
+Pulling is much the same::
+
+ b1.pull(b2)
+
+
+If you have a working tree, as well as a branch, you should use
+WorkingTree.pull, not Branch.pull.
+
+This won't handle conflicts automatically though, so any conflicts will be
+left in the working tree for the user to resolve.
+
+
+Checkout from an existing branch
+================================
+
+This performs a Lightweight checkout from an existing Branch::
+
+ from bzrlib import bzrdir
+
+ accelerator_tree, source = bzrdir.BzrDir.open_tree_or_branch('http:URL')
+ source.create_checkout('/tmp/newBzrCheckout', None, True, accelerator_tree)
+
+
+To make a heavyweight checkout, change the last line to::
+
+ source.create_checkout('/tmp/newBzrCheckout', None, False, accelerator_tree
+
+==================
+History Operations
+==================
+
+Finding the last revision number or id
+======================================
+
+To get the last revision number and id of a branch use::
+
+ revision_number, revision_id = branch.last_revision_info()
+
+
+If all you care about is the revision_id there is also the
+method::
+
+ revision_id = branch.last_revision()
+
+
+Getting the list of revision ids that make up a branch
+======================================================
+
+IMPORTANT: This should be avoided wherever possible, as it scales with the
+length of history::
+
+ revisions = branch.revision_history()
+
+now revisions[0] is the revision id of the first commit, and revs[-1] is the
+revision id of the most recent. Note that if all you want is the last
+revision then you should use branch.last_revision() as described above, as
+it is vastly more efficient.
+
+
+Getting a Revision object from a revision id
+============================================
+
+The Revision object has attributes like "message" to get the information
+about the revision::
+
+ repo = branch.repository
+ revision = repo.get_revision(rev_id)
+
+
+Accessing the files from a revision
+===================================
+
+To get the file contents and tree shape for a specific revision you need
+a RevisionTree. These are supplied by the repository for a specific
+revision id::
+
+ revtree = repo.revision_tree(rev_id)
+
+RevisionTrees, like all trees, can be compared as described in "Comparing
+Trees" above.
+
+The most common way to list files in a tree is ``Tree.iter_entries()``.
+The simplest way to get file content is ``Tree.get_file()``. The best way
+to retrieve file content for large numbers of files `Tree.iter_files_bytes()``
+
=== modified file 'NEWS'
--- a/NEWS 2008-04-07 07:52:50 +0000
+++ b/NEWS 2008-04-08 07:46:55 +0000
@@ -118,6 +118,8 @@
* Reduced the evangelism in the User Guide. (Ian Clatworthy)
+ * Added Integrating with Bazaar document for developers (Martin Albisetti)
+
API BREAKS:
* Attempting to pull data from a ghost aware repository (e.g. knits) into a
=== modified file 'doc/developers/index.txt'
--- a/doc/developers/index.txt 2008-02-29 11:09:08 +0000
+++ b/doc/developers/index.txt 2008-04-08 07:46:55 +0000
@@ -39,6 +39,9 @@
* `Repositories <repository.html>`_ |--| What repositories do and are used for.
+* `Integration Guide <integration.html>`_ |--| A guide to integrate bzrlib into
+ any python application.
+
Data formats
============
More information about the bazaar-commits
mailing list