monotone documentation: Making Changes

Abe decides to do some work on his part of the code. He has a copy of Jim’s database contents, but cannot edit any of that data yet. He begins his editing by checking out the head of the jp.co.juicebot.jb7 branch into a workspace, so he can edit it:

$ mtn --db=abe.mtn --branch=jp.co.juicebot.jb7 checkout .

Monotone unpacks the set of files in the head revision’s manifest directly into Abe’s current directory. (If he had specified something other than . at the end, monotone would have created that directory and unpacked the files into it.) Abe then opens up one of the files, src/apple.c, and edits it:

$ vi src/apple.c
<Abe writes some apple-juice dispensing code>

The file src/apple.c has now been changed. Abe gets up to answer a phone call, and when he returns to his work he has forgotten what he changed. He can ask monotone for details:

$ mtn diff
#
# old_revision [493bda86628fd72c992eb56f73899db9ead3cf6f]
#
# patch "src/apple.c"
#  from [1ce885d2cc59842ff16785834391e864068fbc3c]
#    to [e2c64f6bde75a192d48d2256385df3dd7a963349]
#
============================================================
--- src/apple.c 1ce885d2cc59842ff16785834391e864068fbc3c
+++ src/apple.c e2c64f6bde75a192d48d2256385df3dd7a963349
@ -3,5 +3,8 @ dispense_apple_juice()
 void
 dispense_apple_juice()
 {
-  /* Fill this in please, Abe. */
+  spoutctl(APPLE_SPOUT, FLOW_JUICE, 1);
+  while (spoutctl(APPLE_SPOUT, POLL_JUICE, 1) == 0)
+    usleep (1000);
+  spoutctl(APPLE_SPOUT, FLOW_JUICE, 0);
 }

Abe neglected to provide a --message option specifying the change log on the command line. Monotone therefore invokes an external “log message editor” — typically an editor like vi — with an explanation of the changes being committed and the opportunity to enter a log message.


*** REMOVE THIS LINE TO CANCEL THE COMMIT ***
-- Enter a description of this change above --
-- Edit fields below to modify certificate values --
Branch:    right
Author:    tester@test.net
Date:      2010-09-11T12:03:15

-- Modifications below this line are ignored --
Changes against parent 493bda86628fd72c992eb56f73899db9ead3cf6f

  patched  src/apple.c

Abe enters a single line at the top of the file, saying “polling implementation of src/apple.c”. He then saves the file and quits the editor. Monotone extracts the message to be stored in the associated “changelog” cert. Returning to the shell, Abe’s commit completes:

mtn: beginning commit on branch 'jp.co.juicebot.jb7'
mtn: committed revision 42eae36587508faa664b111cefc291f0b85ef83a

$ mtn sync
mtn: connecting to mtn://jim-laptop.juicebot.co.jp
mtn: finding items to synchronize:
mtn:   certs |    keys | revisions
mtn:       8 |       2 |         2
mtn: bytes in | bytes out | revs in | revs out | revs written
mtn:      615 |      2822 |       0 |        1 |            0
mtn: successful exchange with mtn://jim-laptop.juicebot.co.jp

$ mtn --db=:beth sync "mtn://jim-laptop.juicebot.co.jp?jp.co.juicebot.jb7*"
mtn: connecting to mtn://jim-laptop.juicebot.co.jp
mtn: first time connecting to server mtn://jim-laptop.juicebot.co.jp
mtn: I'll assume it's really them, but you might want to double-check
mtn: their key's fingerprint: 9e9e9ef1d515ad58bfaa5cf282b4a872d8fda00c
mtn: warning: saving public key for jim@juicebot.co.jp to database
mtn: finding items to synchronize:
mtn: bytes in | bytes out | revs in | revs out | revs written
mtn:     4601 |      1239 |       2 |        0 |            1
mtn: verifying new revisions (this may take a while)
mtn: bytes in | bytes out | revs in | revs out | revs written
mtn:     4601 |      1285 |       2 |        0 |            2
mtn: successful exchange with mtn://jim-laptop.juicebot.co.jp

$ mtn --db=:beth --branch=jp.co.juicebot.jb7 checkout juicebot

and since she is using a managed database, monotone automatically remembers the connection between the newly created workspace and the database. She now looks at the output of mtn list databases and sees the following:

$ mtn list databases
:beth.mtn (in /home/beth/.monotone/databases):
        jp.co.juicebot.jb7 (in /home/beth/juicebot)

Beth realizes that, whenever the database of the workspace changes, monotone will adapt the known paths for the old and the new database for her.

But let us get back to the work, Beth now start to edits the file src/banana.c:

$ vi src/banana.c
<Beth writes some banana-juice dispensing code>

and logs her changes in _MTN/log right away so she does not forget what she has done like Abe.

$ vi _MTN/log
* src/banana.c: Added polling implementation

Later, she commits her work. Monotone again invokes an external editor for her to edit her log message, but this time it fills in the messages she’s written so far, and she simply checks them over one last time before finishing her commit:

$ mtn commit
mtn: beginning commit on branch 'jp.co.juicebot.jb7'
mtn: committed revision 85573a54105cd3220db10aa6a0713643cdf5ce6f

$ mtn sync
mtn: connecting to mtn://jim-laptop.juicebot.co.jp
mtn: finding items to synchronize:
mtn:   certs |    keys | revisions
mtn:      12 |       3 |         3
mtn: bytes in | bytes out | revs in | revs out | revs written
mtn:      709 |      2879 |       0 |        1 |            0
mtn: successful exchange with mtn://jim-laptop.juicebot.co.jp

2.10 Making Changes