m7 0.8

m7 0.8

Overview

m7 is a front-end for monotone, a wonderfully rigorous revision control system. Its goal is to make monotone more convenient to use.

m7 offers the following additional features:

Everywhere that m7 displays a revision hash, it will also reveal that revision's "local revision number".
Everywhere that m7 expects a revision id, you can type :<number> and it will select the revision tagged with that local revision number.
There's a new command: tannotate, or tagged annotate, which displays the local revision numbers, and also revision tags, instead of the 40-character hexadecimal revision ids.
m7 has several built-in aliases for longer command-names:

shortcut command

a annotate

c commit

d diff

l log

s status

ta tannotate

ua uannotate

m7 is written in cross-platform Python, and has been tested on Windows, Mac OS X, and Linux. It requires Python 2.3.5 and monotone version 0.30. Also, for m7 to work properly, mtn must be on your path.

Why m7? Because monotone is m followed by seven letters. m7 is designed to save you typing, and I figured the first place I could do that was the name. :)

The default homepage for m7 is here:

http://www.midwinter.com/~larry/programming/m7/

And you can always download a fresh copy here:

http://www.midwinter.com/~larry/programming/m7/m7.zip

Installing m7

Unix

To use m7, just put the shell script somewhere on your path. Make it executable, ensure that the #! first line works for you, and you should probably rename it from m7.py to just m7. Finally, mtn itself should be on your path, too.

Windows

To use m7, just put the shell script somewhere on your path, and make sure .py is listed on your PATHEXT variable. Finally, mtn.exe itself should be on your PATH, too.

Using m7

Day-to-day use of m7 is much the same as monotone. But there are a couple places where the experience is different.

When you run m7 commit, the output might look something like this:

	mtn: beginning commit on branch 'org.hastings.spacegoblin'
	mtn: committed revision affedf26273367eb10efd495a515fecea4d0946b
	m7      : local revision is :67

That last line is new from m7. It's telling you that this is the 67th checkin to this database. This also means you can run m7 log -r :67 --next=1 to see this revision! The output from that command might look like this:

	m7      : expanding :67 to 9f5116143a0ee0ee57761f3d6e44994f96cd4b0a
    -----------------------------------------------------------------
    Revision: :67 9f5116143a0ee0ee57761f3d6e44994f96cd4b0a
    Ancestor: :66 a32e0b9053352bdc6f9ab2b42ea85ed02bb872dd
    Author: larry@hastings.org
    Date: 2006-11-06T01:56:07
    Branch: org.hastings.spacegoblin
	...

You can use this :67 shortcut anywhere m7 takes a revision id.

Best of all is tannotate, or ta for short. It's changed in two ways:

It displays local revision numbers instead of hex revision ids. If the revision has a tag, it displays the tag too.
You can specify an optional final parameter specifying the earliest revision you're interested in seeing identified.

Here's an example of what tannotate looks like. I ran m7 tannotate a.txt and got the following as output:

    # tannotate legend:
    # :1 467b08e6695544577b3896988b7ecaaad5991537 larry@hastings.org 2005-10-22T14:13:27
    # :2 39c669255178579a98d1ecb224cd0889bbb08b70 larry@hastings.org 2005-12-28T11:57:38
    # :3 8ee03ae4f3ac16f7b0ba45fcd97b0e0fa126d932 larry@hastings.org 2005-12-30T14:14:06
    # :4 195b0d6008553cf3722d615cb5e38e44c3be6f50 larry@hastings.org 2006-01-07T00:06:13
    # :5 5e38598b1a75f22db161dc51374d24d7b8b5db82 larry@hastings.org 2006-01-09T01:46:09
    # :6 c435be57c396dcfd66937bb85932e090924712e4 larry@hastings.org 2006-01-16T04:26:46
    # :7 6e0c8ba776cd6cbcef981902f25276e5798d905f larry@hastings.org 2006-01-16T09:47:26

	:1 : first line
	:1 : ZZZ
	:2 : second revision
	:3 : third revision
	:4 : My fourth revision.
	:4 : This one goes on a bit,
	:4 : but sooner or later
	:4 : I'm gonna stop typing.
	:5 : Ah, the fifth revision.
	:6 : What revision number is this?
	:7 : I'm lost.

tannotate will also display tags, when there are any. If revision 4 had a tag cert with the value "Release 1.0", tannotate's output would look like this:

    # tannotate legend:
    #             :1 467b08e6695544577b3896988b7ecaaad5991537 larry@hastings.org 2005-10-22T14:13:27
    #             :2 39c669255178579a98d1ecb224cd0889bbb08b70 larry@hastings.org 2005-12-28T11:57:38
    #             :3 8ee03ae4f3ac16f7b0ba45fcd97b0e0fa126d932 larry@hastings.org 2005-12-30T14:14:06
    # Release 1.0 :4 195b0d6008553cf3722d615cb5e38e44c3be6f50 larry@hastings.org 2006-01-07T00:06:13
    #             :5 5e38598b1a75f22db161dc51374d24d7b8b5db82 larry@hastings.org 2006-01-09T01:46:09
    #             :6 c435be57c396dcfd66937bb85932e090924712e4 larry@hastings.org 2006-01-16T04:26:46
    #             :7 6e0c8ba776cd6cbcef981902f25276e5798d905f larry@hastings.org 2006-01-16T09:47:26

	            :1 : first line
	            :1 : ZZZ
	            :2 : second revision
	            :3 : third revision
	Release 1.0 :4 : My fourth revision.
	Release 1.0 :4 : This one goes on a bit,
	Release 1.0 :4 : but sooner or later
	Release 1.0 :4 : I'm gonna stop typing.
	            :5 : Ah, the fifth revision.
	            :6 : What revision number is this?
	            :7 : I'm lost.

Now let's say I was only interested in what changed in the last three revisions. I ran m7 ta a.txt :5 (used the alias this time!) and got the following as output:

    # tannotate legend:
    # :5 5e38598b1a75f22db161dc51374d24d7b8b5db82 larry@hastings.org 2006-01-09T01:46:09
    # :6 c435be57c396dcfd66937bb85932e090924712e4 larry@hastings.org 2006-01-16T04:26:46
    # :7 6e0c8ba776cd6cbcef981902f25276e5798d905f larry@hastings.org 2006-01-16T09:47:26
    
       : first line
       : ZZZ
       : second revision
       : third revision
       : My fourth revision.
       : This one goes on a bit,
       : but sooner or later
       : I'm gonna stop typing.
    :5 : Ah, the fifth revision.
    :6 : What revision number is this?
    :7 : I'm lost.

If the line hasn't been modified in :5 (or a revision since then), m7 tannotate leaves the revision id blank on that line. Now all the recent changes pop right out at you!

There are two special options for tannotate:

--brief: Supresses the "tannotate legend" at the top. Note that if you specify --brief and don't specify a minimum version number, m7 can skip reviewing the history log for the file, which speeds up tannotate slightly.
--notags: Don't display any tags for the revisions, just list the local revision numbers.

Configuration

m7 uses three monotone database variables, all in the domain org.hastings.m7. Here they are with their defaults:

variable default

preferTannotate 0

revisionPrefix :

autoExecuteDropAndRename 1

Here's what each one does:

preferTannotate: If set to a non-zero value, m7 will use tannotate when you run m7 annotate. If you turn this on, you can still use the original 40-hex-character-id annotate by running m7 uannotate (for untagged annotate).
revisionPrefix: This is the special string m7 looks for at the beginning of a revision id. If you change this to xyz, then m7 cat revision xyz35 would show you the 35th local revision.
autoExecuteDropAndRename: If set to a non-zero value (the default), m7 will automatically add the --execute flag to drop and rename commands. This means monotone will actually delete and rename the files, instead of merely adding those steps to the current "work".

m7 Isn't Perfect

monotone has a wonderful rigor to it. The downside to that rigor is some difficult-to-deal-with UI. (monotone annotate is a good idea, but it is a pain to wade through its output.) The goal of m7 is to make monotone easier to use; sadly, that ease-of-use comes at slight expense. Here is a short list of gotchas and provisos:

m7 is pretty green software yet—it's less like a well-designed system, and more like a cross between a proof-of-concept and some stream-of-consciousness programming. I bet it still has some sharp corners lurking inside. I don't forsee how you could ever lose any data on account of a bug in m7, but you might stub your toe now and then. (Still, there are no guarantees—see the license.)
m7 was written against monotone version 0.30. There are a lot of places where it runs mtn and parses the resulting output; if mtn changes its output in a future version, even slightly, it could break m7. We'll surely update m7 to keep abreast of new releases, but keep in mind that when you update mtn, you should probably check for an update to m7 too. In that same vein, it also uses a db execute command in a critical place, and that could break if the schema is dramatically revised. (Though this now seems unlikely.)

Licensing

Here's the license:

[BEGIN NOTICE]

m7
Copyright 2005-2006 Larry Hastings

This software is provided 'as-is', without any express or implied warranty.
In no event will the authors be held liable for any damages arising from
the use of this software.

Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute
it freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not
   claim that you wrote the original software. If you use this software
   in a product, an acknowledgment in the product documentation would be
   appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be
   misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.

The m7 homepage is here:
	http://www.midwinter.com/~larry/programming/m7/

If you're using m7, I'd love to hear from you!  Email me at
	larry@hastings.org

[END NOTICE]

In non-legalese, my goal was to allow you to do anything you like with the software, except claim that you wrote the original version. If my license prevents you from doing something you'd like to do, contact me and we can discuss it.

Version History

0.8

Sunday, November 5^th, 2006
Major revision. If you are upgrading, please run m7 unpopulate against all your repositories that were exposed to the old m7.

Major revision.
Retooled to use SQLite implicit __ROWID__ from monotone's "revisions" table instead of custom certs for local revision numbers.
Added --brief and --notags options to tannotate.

0.7

Thursday, October 5^th, 2005

Now recoginize ci as an alias for commit.

0.6

Wednesday, October 4^th, 2005

0.5 didn't work correctly. As a matter of fact, it was chock-full of embarassing bugs. Please accept this free upgrade to a working version.

0.5

Monday, October 2^nd, 2005

Sped up m7 generally by not waiting for monotone to finish running before m7 starts processing the output.
Sped up m7 log and m7 tannotate by switching from N list certs commands to a single db execute that produces exactly the information needed.
Changed the output of m7 log so the revision numbers go on the same line as the revision hash ID.

0.4

Friday, September 30^th, 2005

m7 now officially supports monotone 0.23 (and has dropped support for 0.22).
Added auto-execute semantics for drop and rename.

0.3

Thursday, September 29^th, 2005

Changed tannotate so it displays both the m7 "revision tag" and the normal tag (if there is one). If the revision has more than one tag, tannotate displays at most one, picked seemingly at random.
Also, added support for printing out m7's version when --version is specified on the command-line.

0.2

Tuesday, September 27^th, 2005

In response to popular demand, m7 now uses custom certs instead of tags for the local revision numbering scheme.

0.1

Monday, September 26^th, 2005

Initial public release, and with such a confidence-inspiring version number, too.

Happy revision-controlling!

larry

shortcut	command
`a`	`annotate`
`c`	`commit`
`d`	`diff`
`l`	`log`
`s`	`status`
`ta`	`tannotate`
`ua`	`uannotate`

variable	default
`preferTannotate`	`0`
`revisionPrefix`	`:`
`autoExecuteDropAndRename`	`1`