# # add_file "tests/t_rename_dir_add_dir_with_old_name.at" # # patch "AUTHORS" # from [97910e402895c8bbae9ad72fad2e58c9f8965508] # to [d5113319825a1ff4cac54a47f985774b4f5d1b70] # # patch "ChangeLog" # from [610b18234a1280d9840a5cb47c32cb7572df84d9] # to [15b5a7c02b727b014a94957cfbf468a2371d5af1] # # patch "monotone.texi" # from [82e309cffe8832da1e871c00c9795af49531f1df] # to [17687a1f93e1694cb6433d5e878ce3a00c08cd7f] # # patch "tests/t_rename_dir_add_dir_with_old_name.at" # from [] # to [20a0beb813e9b6231c13fada0408b1e876db7a3a] # # patch "testsuite.at" # from [14b8600c48fdafc19eba6942e2270738b4bd8c71] # to [9b5ee1d188f44dc8a2deb7b9a69a022f8dd2155e] # --- AUTHORS +++ AUTHORS @@ -52,6 +52,7 @@ Jon Bright Corey Halpin Jeremy Cowgar + Martin Dvorak supporting files: --- ChangeLog +++ ChangeLog @@ -1,3 +1,18 @@ +2005-04-16 Nathaniel Smith + + * monotone.texi (Network Service): Rewrite to include former + Exchanging Keys section. + (Branching and Merging): New tutorial section, inspired by a patch + from Martin Kihlgren . + (CVS Phrasebook): Add "Importing a New Project". + + * AUTHORS: Add Martin Dvorak. + +2005-04-15 Martin Dvorak + + * tests/t_rename_dir_add_dir_with_old_name.at: New test. + * testsuite.at: Add it. + 2005-04-16 Matt Johnston * change_set.cc (compose_rearrangement): remove logging statements --- monotone.texi +++ monotone.texi @@ -212,11 +212,11 @@ @end ifnotinfo Version control systems, such as monotone, are principally concerned -with the storage and management of @i{multiple} versions of some -files. One way to store multiple versions of a file is, literally, to -save a separate @i{complete} copy of the file, every time you make a +with the storage and management of @i{multiple} versions of some files. +One way to store multiple versions of a file is, literally, to save a +separate @i{complete} copy of the file, every time you make a change. When necessary, monotone will save complete copies of your -files in their, compressed with the @command{zlib} compression format. +files, compressed with the @command{zlib} compression format. @ifinfo @smallexample @@ -1071,13 +1071,13 @@ @menu * Creating a Database:: * Generating Keys:: -* Exchanging Keys:: * Starting a New Project:: * Adding Files:: * Committing Work:: * Network Service:: * Making Changes:: * Dealing with a Fork:: +* Branching and Merging:: @end menu @@ -1221,82 +1221,10 @@ Abe and Beth do the same, with their secret passphrases. @page address@hidden Exchanging Keys address@hidden Exchanging Keys - -Jim, Abe and Beth all wish to work with one another, and trust one -another. For monotone to accept this situation, the team members will -need to exchange the public parts of their @sc{rsa} key with each -other. - -First, Jim exports his public key: - address@hidden address@hidden -$ monotone --db=~/jim.db pubkey jim@@juicebot.co.jp >~/jim.pubkey address@hidden group address@hidden smallexample - -His public key is just a plain block of ASCII text: - address@hidden address@hidden -$ cat ~/jim.pubkey -[pubkey jim@@juicebot.co.jp] -MIGdMA0GCSqGSIb3DQEBAQUAA4GLADCBhwKBgQCbaVff9SF78FiB/1nUdmjbU/TtPyQqe/fW -CDg7hSg1yY/hWgClXE9FI0bHtjPMIx1kBOig09AkCT7tBXM9z6iGWxTBhSR7D/qsJQGPorOD -DO7xovIHthMbZZ9FnvyB/BCyiibdWgGT0Gtq94OKdvCRNuT59e5v9L4pBkvajb+IzQIBEQ== -[end] address@hidden group address@hidden smallexample - -Abe also exports his public key: - address@hidden address@hidden -$ monotone --db=~/abe.db pubkey abe@@juicebot.co.jp >~/abe.pubkey address@hidden group address@hidden smallexample - -As does Beth: - address@hidden address@hidden -$ monotone --db=~/beth.db pubkey beth@@juicebot.co.jp >~/beth.pubkey address@hidden group address@hidden smallexample - -Then all three team members exchange keys. The keys are not secret, -but the team members must be relatively certain that they are -communicating with the person they intend to trust, when exchanging -keys, and not some malicious person pretending to be a team -member. Key exchange may involve sending keys over an encrypted -medium, or meeting in person to exchange physical copies, or any -number of techniques. All that matters, ultimately, is for each team -member to receive the keys of the others. - -So eventually, after key exchange, Jim has Beth's and Abe's public key -files in his home directory, along with his own. He tells monotone to -read the associated key packets into his database: - address@hidden address@hidden -$ monotone --db=~/jim.db read <~/abe.pubkey -monotone: read 1 packet -$ monotone --db=~/jim.db read <~/beth.pubkey -monotone: read 1 packet address@hidden group address@hidden smallexample - -Beth and Abe similarly tell monotone to read read the two new public -keys they received into their respective databases. - - address@hidden @node Starting a New Project @section Starting a New Project -Before they can begin work on the project, Jim needs to create a +Before he can begin work on the project, Jim needs to create a @i{working copy} --- a directory whose contents monotone will keep track of. Often, one works on projects that someone else has started, and creates working copies with the @code{checkout} command, which you'll @@ -1529,10 +1457,7 @@ @smallexample @group $ monotone --db=jim.db --branch=jp.co.juicebot.jb7 commit --message='initial checkin of project' -monotone: beginning commit -monotone: manifest 2098eddbe833046174de28172a813150a6cbda7b -monotone: revision 2e24d49a48adf9acf3a1b6391a080008cbef9c21 -monotone: branch jp.co.juicebot.jb7 +monotone: beginning commit on branch 'jp.co.juicebot.jb7' monotone: committed revision 2e24d49a48adf9acf3a1b6391a080008cbef9c21 @end group @end smallexample @@ -1643,12 +1568,68 @@ @section Network Service Jim now decides he will make his base revision available to his -employees. To do this first adds a small amount of extra information -to his @file{.monotonerc} file, permitting Abe and Beth to access his -database: +employees. To do this he gives Abe and Beth permission to access his +database. There are two parts to this: first, he has to get a copy of +each of their public keys; then, he has to tell monotone that the +holders of those keys are permitted to access his database. +First, Abe exports his public key: + @smallexample @group +$ monotone --db=~/abe.db pubkey abe@@juicebot.co.jp >~/abe.pubkey address@hidden group address@hidden smallexample + +His public key is just a plain block of ASCII text: + address@hidden address@hidden +$ cat ~/abe.pubkey +[pubkey abe@@juicebot.co.jp] +MIGdMA0GCSqGSIb3DQEBAQUAA4GLADCBhwKBgQCbaVff9SF78FiB/1nUdmjbU/TtPyQqe/fW +CDg7hSg1yY/hWgClXE9FI0bHtjPMIx1kBOig09AkCT7tBXM9z6iGWxTBhSR7D/qsJQGPorOD +DO7xovIHthMbZZ9FnvyB/BCyiibdWgGT0Gtq94OKdvCRNuT59e5v9L4pBkvajb+IzQIBEQ== +[end] address@hidden group address@hidden smallexample + +Beth also exports her public key: + address@hidden address@hidden +$ monotone --db=~/beth.db pubkey beth@@juicebot.co.jp >~/beth.pubkey address@hidden group address@hidden smallexample + +Then Abe and Beth both send their keys to Jim. The keys are not secret, +but the team members must be relatively certain that they are +communicating with the person they intend to trust, when exchanging +keys, and not some malicious person pretending to be a team +member. Key exchange may involve sending keys over an encrypted +medium, or meeting in person to exchange physical copies, or any +number of techniques. All that matters, ultimately, is that Jim receive +both Abe and Beth's key. + +So eventually, after key exchange, Jim has the public key files in his +home directory. He tells monotone to read the associated key packets +into his database: + address@hidden address@hidden +$ monotone --db=~/jim.db read <~/abe.pubkey +monotone: read 1 packet +$ monotone --db=~/jim.db read <~/beth.pubkey +monotone: read 1 packet address@hidden group address@hidden smallexample + +Now Jim's monotone is able to identify Beth and Abe, and he is ready to +give them permission to access his database. He does this by adding a +small amount of extra information to his @file{.monotonerc} file: + address@hidden address@hidden $ cat >>~/.monotonerc function get_netsync_read_permitted (collection, identity) if (identity == "abe@@juicebot.co.jp") then return true end @@ -1719,8 +1700,9 @@ always running; this way, everyone always knows where to go to get the latest changes, and people can push their changes out without first calling their friends and making sure that they have their servers -running. To support this style of working, monotone remembers the first -server you use, and makes that the default for future operations. +running. To make this style of working more convenient, monotone +remembers the first server you use, and makes that the default for +future operations. @page @node Making Changes @@ -1785,10 +1767,8 @@ @smallexample @group $ monotone commit -monotone: beginning commit -monotone: manifest b33cb337dccf21d6673f462d677a6010b60699d1 -monotone: revision 70decb4b31a8227a629c0e364495286c5c75f979 -monotone: branch jp.co.juicebot.jb7 +monotone: beginning commit on branch 'jp.co.juicebot.jb7' +monotone: commited revision 70decb4b31a8227a629c0e364495286c5c75f979 @end group @end smallexample @@ -1894,10 +1874,7 @@ @smallexample @group $ monotone commit -monotone: beginning commit -monotone: manifest eaebc3c558d9e30db6616ef543595a5a64cc6d5f -monotone: revision 80ef9c9d251d39074d37e72abf4897e0bbae1cfb -monotone: branch jp.co.juicebot.jb7 +monotone: beginning commit on branch 'jp.co.juicebot.jb7' monotone: committed revision 80ef9c9d251d39074d37e72abf4897e0bbae1cfb @end group @end smallexample @@ -2012,10 +1989,7 @@ @smallexample @group $ monotone commit --message='interrupt implementation of src/banana.c' -monotone: beginning commit -monotone: manifest de81e46acb24b2950effb18572d5166f83af3881 -monotone: revision 8b41b5399a564494993063287a737d26ede3dee4 -monotone: branch jp.co.juicebot.jb7 +monotone: beginning commit on branch 'jp.co.juicebot.jb7' monotone: committed revision 8b41b5399a564494993063287a737d26ede3dee4 @end group @end smallexample @@ -2126,6 +2100,95 @@ step) and your committed state is still safe. It is therefore recommended that you commit your work @emph{first}, before merging. address@hidden address@hidden Branching and Merging address@hidden Branching and Merging + +So by now you're familiar with making changes, sharing them with other +people, and integrating your changes with their changes. Sometimes, +though, you may want to make some changes, and @emph{not} integrate them +with other people's --- or at least not right away. One way to do this +would be to simply never run @command{monotone merge}; but it would +quickly become confusing to try and keep track of which changes were in +which revisions. This is where @emph{branches} are useful. + +Continuing our example, suppose that Jim is so impressed by Beth's work +on banana juice support that he assigns her to work on the JuiceBot 7's +surprise new feature: muffins. In the mean time, Abe will continue +working on the JuiceBot's basic juice-related function. + +The changes required to support muffins are somewhat complicated, and +Beth is worried that her work might destabilize the program, and +interfere with Abe's work. In fact, she isn't even sure her first +attempt will turn out to be the right approach; she might work on it for +a while and then decide it was a bad idea, and should be discarded. For +all these reasons, she decides that she will work on a branch, and then +once she is satisfied with the new code, she will merge back onto the +mainline. + +She decides that since main development is in branch address@hidden, she will use branch address@hidden So, she makes the first few edits to +the new muffins code, and commits it on a new branch by simply passing address@hidden to commit: + address@hidden address@hidden +$ monotone commit --branch=jp.co.juicebot.jb7.muffins --message='initial autobake framework' +monotone: beginning commit on branch 'jp.co.juicebot.jb7.muffins' +monotone: committed revision d33caefd61823ecbb605c39ffb84705dec449857 address@hidden group address@hidden smallexample + +That's all there is to it --- now there is a address@hidden branch, with her initial checkin on +it. She can make further checkins from the same working copy, and they +will automatically go to the muffins branch; if anyone else wants to +help her work on muffins, they can check out that branch as usual. + +Of course, while Beth is working on the new muffins code, Abe is still +making fixes to the main line. Occasionally, Beth wants to integrate +his latest work into the muffins branch, so that her version doesn't +fall too far behind. She does this by using the @command{propagate} +command: + address@hidden address@hidden +$ monotone propagate jp.co.juicebot.jb7 jp.co.juicebot.jb7.muffins +monotone: propagating jp.co.juicebot.jb7 -> jp.co.juicebot.jb7.muffins +monotone: [source] da003f115752ac6e4750b89aaca9dbba178ac80c +monotone: [target] d0e5c93bb61e5fd25a0dadf41426f209b73f40af +monotone: common ancestor 853b8c7ac5689181d4b958504adfb5d07fd959ab found address@hidden group address@hidden smallexample + +The @command{propagate} merges all of the new changes on one branch onto +another. + +When the muffins code is eventually stable and ready to be integrated +into the main line of development, she simple propagates the other way: + address@hidden address@hidden +$ monotone propagate jp.co.juicebot.jb7.muffins jp.co.juicebot.jb7 +monotone: propagating jp.co.juicebot.jb7 -> jp.co.juicebot.jb7.muffins +monotone: [source] 4e48e2c9a3d2ca8a708cb0cc545700544efb5021 +monotone: [target] bd29b2bfd07644ab370f50e0d68f26dcfd3bb4af +monotone: common ancestor 652b1035343281a0d2a5de79919f9a31a30c9028 found address@hidden group address@hidden smallexample + +Monotone always records the full history of all merges, and is designed +to handle an arbitrarily complicated graph of changes. You can make a +branch, then branch off from that branch, propagate changes between +arbitrary branches, and so on; monotone will track all of it, and do +something sensible for each merge. Of course, it is still probably a +good idea to come up with some organization of branches and a plan for +which should be merged to which other ones. Monotone may keep track of +graphs of arbitrary complexity; but, you will have more trouble. +Whatever arrangement of branches you come up with, though, monotone +should be able to handle it. + @node Advanced Uses @chapter Advanced Uses @@ -2942,7 +3005,7 @@ @tab @smallexample @group -$ monotone diff 3e7db 278df +$ monotone diff -r 3e7db -r 278df @end group @end smallexample @end multitable @@ -3024,6 +3087,29 @@ manifest of the current revision. address@hidden Importing a New Project + address@hidden @columnfractions .4 .4 address@hidden address@hidden address@hidden +$ cvs import wobbler vendor start address@hidden group address@hidden smallexample address@hidden address@hidden address@hidden +$ monotone --db=/path/to/database.db --branch=com.foo.wobbler setup . +$ monotone add . +$ monotone commit address@hidden group address@hidden smallexample address@hidden multitable + +The @command{setup} command turns an ordinary directory into a +monotone working copy. After that, you can add your files and commit +them as usual. + @heading Initializing a Repository @multitable @columnfractions .4 .4 --- tests/t_rename_dir_add_dir_with_old_name.at +++ tests/t_rename_dir_add_dir_with_old_name.at @@ -0,0 +1,25 @@ +# -*- Autoconf -*- + +AT_SETUP([renaming a directory and then adding a new with the old name]) + +MONOTONE_SETUP + +# add 'foo/test' file +AT_CHECK(mkdir foo) +AT_DATA(foo/test, [test file in foo dir +]) +AT_CHECK(MONOTONE add foo, [], [ignore], [ignore]) +COMMIT(testbranch) + +# rename 'foo' dir to 'bar' +AT_CHECK(MONOTONE rename foo bar, [], [ignore], [ignore]) +AT_CHECK(mv foo bar) + +# add new 'foo' dir +AT_CHECK(mkdir foo) +AT_DATA(foo/test, [test file in new foo dir +]) +AT_CHECK(MONOTONE add foo, [], [ignore], [ignore]) +COMMIT(testbranch) + +AT_CLEANUP --- testsuite.at +++ testsuite.at @@ -551,3 +551,4 @@ m4_include(tests/t_netsync_largish_file.at) m4_include(tests/t_update_off_branch.at) m4_include(tests/t_setup_checkout_modify_new_dir.at) +m4_include(tests/t_rename_dir_add_dir_with_old_name.at)