[Monotone-devel] [RFC] ideas for an automate status command

[Derek Scherger]

I've been thinking for a while of some form of status command that can
be used for things like IDE plugins or monotone.el lisp modes to get the
status of *every* file in a working directory. Currently status only
lists changed files, and fails if there are any missing files, making it
rather unsuitable for automated use by a plugin.

Presumably such an automate command and would be named something like

        $ monotone automate files
        $ monotone automate inventory
        $ monotone automate status

any preferences? Somehow "inventory" feels to me like it would be
listing things from the database (i.e. warehouse) rather than in the
current working copy (i.e. my house) but I'm sure I could be convinced
of otherwise.

The next thing to work out is the output format for such a command. In
thie following proposal, files are generally listed one per line, with a
single character status preceeding them. For example:

        ? file1
        ~ file2
        ! file3

representing missing (?), ignored (~) and unknown (!) files
respectively. note that this is not quite the same as svn, which uses ?
for unknown and ! for missing I think and perhaps *not* changing this
would be a better idea.

        + file4
        - file5
        # file6
        = file7

representing added (+), dropped (-), changed/patched (#), unchanged (=)
files respectively.

renames would be the exception to the one file per line rule and could
be represented by

        % file8 file9
        % file10 file8

using % as a means to represent old/new names. note that there are
several minor issues with renames.

one issue is that renamed files may also be changed (i.e. edited) but
I'm not sure whether this information is particularly interesting or
not. from a plugin perspective, a file that has changed by being renamed
or by being edited has become "committable" and needs to be marked as
such. if we really do want to represent renamed and edited files a #
line on the target name could be included or some other flag character
representing renamed-and-changed could be used.

another issue is that rename a b; rename b a is supported by monotone
meaning that the two files have been swapped. an intermediate rename
step is required to get to this point but the resulting changeset will
have only two renames. in some IDE's cvs renames are indicated as
drop/add pairs and coloured red and green for example. having renames
going both ways might complicate this a bit!

and yet another issues is that rename foo bar; rename baz foo is also
supported by monotone. these seem to appear in the serialized changeset
in the correct order but monotone views them as "simultaneous
operations" as I understand it. this suggests that the order of files in
the output from automate status might need to be something like unknown,
missing, ignored, dropped, renamed, added, changed, unchanged rather
than in sorted pathname order with the appropriate status prefixes which
would seem nicer in some ways I think.

the ability to drop and rename directories (even though it is currently
somewhat broken and doesn't include explicit addition of directories)
also adds some issues. the first one that comes to mind is how to
distinguish directories from files, and I'm wondering if simply keeping
a "/" suffix would be sufficient? for example:

        + dir1/
        % dir2/ dir3/
        - dir4/

throughout all of this, paths may contain spaces (and possibly quotes)
and will need to be quoted and escaped properly, whatever that might be.

whether or not this should be an automate command is something else I'm
wondering about. it seems that this format might be more like what
people coming from cvs or svn would be expecting out of status or some
similar command? an option (--all) to show all files, verses only the
changes would probably be good in this case.

after discussing this with njs on irc the other night we had arrived a a
completely different format.

        123 file

where 123 are 3 or more different columns of status with 1 being the
pre-state info, 2 being the post-state info and 3 being a flag
indicating changes to the file. with adds represented as A in 1, drops
as D in 2, renames as R in 1 for the old name and R in 2 for the new
name, on two separate lines. also needed for renames would be identifier
columns to tie the two associated lines together and to support the
swapping and other more complicated rename cases mentioned above.

so, comments, ideas, feedback?

Cheers,
Derek