# # # patch "ChangeLog" # from [26f17be23e4c617836a891feb2a75508c958a6bf] # to [be7ddaa94a2b2a1c91d6f5cda74d20fb35f0ae17] # # patch "automate.cc" # from [5e1910efbdc8a8356902e3cee539e9ac2895f51b] # to [463daa3a2ca617b20765d737b26345d20fa81b26] # # patch "database_check.cc" # from [6f585f646313fa04eadb58230d9ba98d8d82dbed] # to [e0b4947bd0c1533a18b84412a3e560dd63847f47] # # patch "monotone.texi" # from [55108706b1bdcfe1eb8c17883f8a694f9bf57d75] # to [c1f6f303f3ca42703f7cf8c8aeca51c1d954d526] # ============================================================ --- ChangeLog 26f17be23e4c617836a891feb2a75508c958a6bf +++ ChangeLog be7ddaa94a2b2a1c91d6f5cda74d20fb35f0ae17 @@ -1,5 +1,19 @@ 2006-04-08 Nathaniel Smith + * monotone.texi: Several little content improvements, scattered + throughout. + (Automation): Document new rev and manifest formats. Document new + packet commands. + * database_check.cc: Add a comment to warn people that there are + detailed docs on this, so if they add new stuff they'll want to + add new docs too. + * automate.cc (automate_get_manifest_of, automate_get_revision): + Re-sync docs to manual. + (automate_packet_for_fdata): Fix copy/paste error in error + message. + +2006-04-08 Nathaniel Smith + * netxx/resolve_gethostbyname.cxx (resolve_hostname): #ifdef out Win32-incompatible error reporting call. ============================================================ --- automate.cc 5e1910efbdc8a8356902e3cee539e9ac2895f51b +++ automate.cc 463daa3a2ca617b20765d737b26345d20fa81b26 @@ -894,37 +894,61 @@ // Arguments: // 1: a revision id (optional, determined from the workspace if non-existant) // Added in: 1.0 -// Purpose: Prints changeset information for the specified revision id. +// Purpose: Prints change information for the specified revision id. +// There are several changes that are described; each of these is described by +// a different basic_io stanza. The first string pair of each stanza indicates the +// type of change represented. // -// There are several changes that are described; each of these is described by -// a different basic_io stanza. The first string pair of each stanza indicates the -// type of change represented. +// All stanzas are formatted by basic_io. Stanzas are separated +// by a blank line. Values will be escaped, '\' to '\\' and +// '"' to '\"'. // -// Possible values of this first value are along with an ordered list of -// basic_io formatted string pairs that will be provided are: +// Possible values of this first value are along with an ordered list of +// basic_io formatted stanzas that will be provided are: // -// 'old_revision' : represents a parent revision. -// format: ('old_revision', revision id) -// 'new_manifest' : represents the new manifest associated with the revision. -// format: ('new_manifest', manifest id) -// 'old_manifest' : represents a manifest associated with a parent revision. -// format: ('old_manifest', manifest id) -// 'patch' : represents a file that was modified. -// format: ('patch', filename), ('from', file id), ('to', file id) -// 'add_file' : represents a file that was added. -// format: ('add_file', filename) -// 'delete_file' : represents a file that was deleted. -// format: ('delete_file', filename) -// 'delete_dir' : represents a directory that was deleted. -// format: ('delete_dir', filename) -// 'rename_file' : represents a file that was renamed. -// format: ('rename_file', old filename), ('to', new filename) -// 'rename_dir' : represents a directory that was renamed. -// format: ('rename_dir', old filename), ('to', new filename) +// 'format_version' +// used in case this format ever needs to change. +// format: ('format_version', the string "1") +// occurs: exactly once +// 'new_manifest' +// represents the new manifest associated with the revision. +// format: ('new_manifest', manifest id) +// occurs: exactly one +// 'old_revision' +// represents a parent revision. +// format: ('old_revision', revision id) +// occurs: either one or two times +// 'delete +// represents a file or directory that was deleted. +// format: ('delete', path) +// occurs: zero or more times +// 'rename' +// represents a file or directory that was renamed. +// format: ('rename, old filename), ('to', new filename) +// occurs: zero or more times +// 'add_dir' +// represents a directory that was added. +// format: ('add_dir, path) +// occurs: zero or more times +// 'add_file' +// represents a file that was added. +// format: ('add_file', path), ('content', file id) +// occurs: zero or more times +// 'patch' +// represents a file that was modified. +// format: ('patch', filename), ('from', file id), ('to', file id) +// occurs: zero or more times +// 'clear' +// represents an attr that was removed. +// format: ('clear', filename), ('attr', attr name) +// occurs: zero or more times +// 'set' +// represents an attr whose value was changed. +// format: ('set', filename), ('attr', attr name), ('value', attr value) +// occurs: zero or more times // -// Output format: All stanzas are formatted by basic_io. Stanzas are seperated -// by a blank line. Values will be escaped, '\' -> '\\' and '"' -> '\"'. -// +// These stanzas will always occur in the order listed here; stanzas of +// the same type will be sorted by the filename they refer to. // Error conditions: If the revision specified is unknown or invalid prints an // error message to stderr and exits with status 1. static void @@ -965,12 +989,42 @@ // Name: get_manifest_of // Arguments: -// 1: a revision id (optional, determined from the workspace if non-existant) +// 1: a revision id (optional, determined from the workspace if not given) // Added in: 2.0 // Purpose: Prints the contents of the manifest associated with the given revision ID. // -// Output format: A basic_io string containing the manifest. +// Output format: +// There is one basic_io stanza for each file or directory in the +// manifest. // +// All stanzas are formatted by basic_io. Stanzas are separated +// by a blank line. Values will be escaped, '\' to '\\' and +// '"' to '\"'. +// +// Possible values of this first value are along with an ordered list of +// basic_io formatted stanzas that will be provided are: +// +// 'format_version' +// used in case this format ever needs to change. +// format: ('format_version', the string "1") +// occurs: exactly once +// 'dir': +// represents a directory. The path "" (the empty string) is used +// to represent the root of the tree. +// format: ('dir', pathname) +// occurs: one or more times +// 'file': +// represents a file. +// format: ('file', pathname), ('content', file id) +// occurs: zero or more times +// +// In addition, 'dir' and 'file' stanzas may have attr information +// included. These are appended to the stanza below the basic dir/file +// information, with one line describing each attr. These lines take the +// form ('attr', attr name, attr value). +// +// Stanzas are sorted by the path string. +// // Error conditions: If the revision ID specified is unknown or invalid prints an // error message to stderr and exits with status 1. static void @@ -1122,7 +1176,7 @@ file_data f_data; N(app.db.file_version_exists(f_id), - F("no such revision '%s'") % f_id); + F("no such file '%s'") % f_id); app.db.get_file_version(f_id, f_data); pw.consume_file_data(f_id,f_data); } @@ -1130,7 +1184,7 @@ // Name: packet_for_fdelta // Arguments: // 1: a file id -// 1: a file id +// 2: a file id // Added in: 2.0 // Purpose: Prints the file delta in packet format // ============================================================ --- database_check.cc 6f585f646313fa04eadb58230d9ba98d8d82dbed +++ database_check.cc e0b4947bd0c1533a18b84412a3e560dd63847f47 @@ -840,6 +840,12 @@ missing_certs, mismatched_certs, unchecked_sigs, bad_sigs); + // NOTE: any new sorts of problems need to have added: + // -- a message here, that tells the use about them + // -- entries in one _or both_ of the sums calculated at the end + // -- an entry added to the manual, which describes in detail why the + // error occurs and what it means to the user + if (missing_files > 0) W(F("%d missing files\n") % missing_files); if (unreferenced_files > 0) ============================================================ --- monotone.texi 55108706b1bdcfe1eb8c17883f8a694f9bf57d75 +++ monotone.texi c1f6f303f3ca42703f7cf8c8aeca51c1d954d526 @@ -2981,13 +2981,16 @@ @table @code @item default-exclude-pattern The default branch exclusion glob pattern for netsync operations to -use. Automatically set by first use of netsync. +use. Automatically set by first use of netsync, and by any netsync +that uses the @option{--set-default} option. @item default-include-pattern The default branch glob pattern for netsync operations to use. -Automatically set by first use of netsync. +Automatically set by first use of netsync, and by any netsync that +uses the @option{--set-default} option. @item default-server The default server for netsync operations to use. Automatically set -by first use of netsync. +by first use of netsync, and by any netsync that uses the address@hidden option. @end table @item known-servers @@ -3045,6 +3048,13 @@ Any file in the directory @file{_MTN/} @end table +The general intention is that versioned control files are things that +you may want to edit directly. In comparison, you should never have +to edit non-versioned control files directly; monotone should do that +for you whenever it is appropriate. However, both are documented +here, just in case a situation arises where you need to go ``under the +hood''. + @heading Existing control files The following control files are currently used. More control files may be added @@ -3700,6 +3710,8 @@ @smallexample @group +dir "" + file "Makefile" content [84e2c30a2571bd627918deee1e6613d34e64a29e] @@ -3714,6 +3726,7 @@ Then the following files are created: @smallexample @group address@hidden/ @var{directory}/Makefile @var{directory}/include/hello.h @var{directory}/src/hello.c @@ -4196,9 +4209,9 @@ In particular, it prints: @itemize @item -The ``base revision ID'' and ``base manifest ID'', which are -referenced by the file @file{_MTN/revision}, and which your workspace -is an in-progress descendent of. +The ``base revision ID'', which is referenced by the file address@hidden/revision}, and which your workspace is an in-progress +descendent of. @item The ``current manifest ID'', which is the ID of the manifest which results from applying @file{_MTN/work} to the base manifest, and @@ -4627,38 +4640,37 @@ convenient to read and write packets. @emph{Note:} earlier versions of monotone queued and replayed packet -streams for their networking system. This older networking system is -deprecated and will be removed in a future version, as the netsync -protocol has several properties which make it advantageous as a -communication system. However, the packet i/o facility will remain in -monotone as a utility for moving individual data items around -manually. +streams for their networking system. This older networking system has +been removed, as the netsync protocol has several properties which +make it a superior communication system. However, the packet I/O +facility will remain in monotone as a utility for moving individual +data items around manually. @ftable @command address@hidden monotone certs @var{id} address@hidden monotone automate packets_for_certs @var{id} This command prints out an @code{rcert} packet for each cert in your database associated with @var{id}. These can be used to transport -certificates safely between monotone databases. +certificates safely between monotone databases. See @ref{Automation} +for details of this command. address@hidden monotone fdata @var{id} address@hidden monotone mdata @var{id} address@hidden monotone rdata @var{id} address@hidden monotone automate packet_for_fdata @var{id} address@hidden monotone automate packet_for_rdata @var{id} -These commands print out an @code{fdata}, @code{mdata} or @code{rdata} -packet for the file, manifest or revision @var{id} in your database. -These can be used to transport files, manifests or revisions, in their -entirety, safely between monotone databases. +These commands print out an @code{fdata} or @code{rdata} packet for +the file, manifest or revision @var{id} in your database. These can +be used to transport files or revisions, in their entirety, safely +between monotone databases. See @ref{Automation} for details of these +commands. address@hidden monotone automate packet_for_fdelta @var{id1} @var{id2} address@hidden monotone fdelta @var{id1} @var{id2} address@hidden monotone mdelta @var{id1} @var{id2} +This command prints out an @code{fdelta} packet for the differences +between file versions @var{id1} and @var{id2}, in your database. +These can be used to transport file differences safely between +monotone databases. See @ref{Automation} for details of this +command. -These commands print out an @code{fdelta} or @code{mdelta} packet for -the differences between file or manifest versions @var{id1} and address@hidden, in your database. These can be used to transport file or -manifest differences safely between monotone databases. - @item monotone privkey @var{keyid} @itemx monotone pubkey @var{keyid} @@ -5837,45 +5849,8 @@ @item Purpose: -Prints changeset information for the specified revision id. +Prints change information for the specified revision id. -There are several changes that are described; each of these is described by -a different basic_io stanza. The first string pair of each stanza indicates the -type of change represented. - -Possible values of this first value are along with an ordered list of -basic_io formatted string pairs that will be provided are: - address@hidden -'old_revision' - represents a parent revision. - format: ('old_revision', revision id) -'new_manifest' - represents the new manifest associated with the revision. - format: ('new_manifest', manifest id) -'old_manifest' - represents a manifest associated with a parent revision. - format: ('old_manifest', manifest id) -'patch' - represents a file that was modified. - format: ('patch', filename), ('from', file id), ('to', file id) -'add_file' - represents a file that was added. - format: ('add_file', filename) -'delete_file' - represents a file that was deleted. - format: ('delete_file', filename) -'delete_dir' - represents a directory that was deleted. - format: ('delete_dir', filename) -'rename_file' - represents a file that was renamed. - format: ('rename_file', old filename), ('to', new filename) -'rename_dir' - represents a directory that was renamed. - format: ('rename_dir', old filename), ('to', new filename) address@hidden verbatim - @item Sample output: @verbatim @@ -5896,10 +5871,63 @@ @item Output format: +There are several changes that are described; each of these is described by +a different basic_io stanza. The first string pair of each stanza indicates the +type of change represented. + All stanzas are formatted by basic_io. Stanzas are separated by a blank line. Values will be escaped, '\' to '\\' and '"' to '\"'. +Possible values of this first value are along with an ordered list of +basic_io formatted stanzas that will be provided are: + address@hidden +'format_version' + used in case this format ever needs to change. + format: ('format_version', the string "1") + occurs: exactly once +'new_manifest' + represents the new manifest associated with the revision. + format: ('new_manifest', manifest id) + occurs: exactly one +'old_revision' + represents a parent revision. + format: ('old_revision', revision id) + occurs: either one or two times +'delete + represents a file or directory that was deleted. + format: ('delete', path) + occurs: zero or more times +'rename' + represents a file or directory that was renamed. + format: ('rename, old filename), ('to', new filename) + occurs: zero or more times +'add_dir' + represents a directory that was added. + format: ('add_dir, path) + occurs: zero or more times +'add_file' + represents a file that was added. + format: ('add_file', path), ('content', file id) + occurs: zero or more times +'patch' + represents a file that was modified. + format: ('patch', filename), ('from', file id), ('to', file id) + occurs: zero or more times +'clear' + represents an attr that was removed. + format: ('clear', filename), ('attr', attr name) + occurs: zero or more times +'set' + represents an attr whose value was changed. + format: ('set', filename), ('attr', attr name), ('value', attr value) + occurs: zero or more times address@hidden verbatim + +These stanzas will always occur in the order listed here; stanzas of +the same type will be sorted by the filename they refer to. + @item Error conditions: If the revision specified is unknown or invalid prints an error message @@ -5993,6 +6021,10 @@ file "tarofbranch.psp" content [be83f459a152ffd49d89d69555f870291bc85311] + file "test.py" +content [e65aace9237833ec775253cfde97f59a0af5bc3d] + attr "mtn:execute" "true" + file "utility.py" content [fb51955563d64e628e0e67e4acca1a1abc4cd989] @@ -6008,13 +6040,42 @@ @item Output format: -The output format is one line for each file in the manifest. Each line begins -with a 40 character file ID, followed by two space characters (' ') and then -the filename. +There is one basic_io stanza for each file or directory in the +manifest. +All stanzas are formatted by basic_io. Stanzas are separated +by a blank line. Values will be escaped, '\' to '\\' and +'"' to '\"'. + +Possible values of this first value are along with an ordered list of +basic_io formatted stanzas that will be provided are: + address@hidden +'format_version' + used in case this format ever needs to change. + format: ('format_version', the string "1") + occurs: exactly once +'dir': + represents a directory. The path "" (the empty string) is used + to represent the root of the tree. + format: ('dir', pathname) + occurs: one or more times +'file': + represents a file. + format: ('file', pathname), ('content', file id) + occurs: zero or more times address@hidden verbatim + +In addition, 'dir' and 'file' stanzas may have attr information +included. These are appended to the stanza below the basic dir/file +information, with one line describing each attr. These lines take the +form ('attr', attr name, attr value). + +Stanzas are sorted by the path string. + @item Error conditions: -If the manifest ID specified is unknown or invalid prints an error +If the revision ID specified is unknown or invalid prints an error message to stderr and exits with status 1. @end table @@ -6105,6 +6166,186 @@ @end table address@hidden monotone automate packet_for_rdata @var{id} + address@hidden @strong address@hidden Arguments: + +The @var{id} specifies the revision to output an rdata packet for. + address@hidden Added in: + +2.0 + address@hidden Purpose: + +Prints the revision data in packet format + address@hidden Sample output: + address@hidden +[rdata bdf3b10b5df0f17cc6c1b4b3351d84701bda59ed] +H4sIAAAAAAAA/0XQS27DMAwE0L1PIfgArb4kte62NzACg5SoJEBsF7aRurev0UVzgJl5mLas +E+/jU9ftvsymd33Xzfo9Tjzfm267GSgGwVarz6Valx0KtFYwii9VqUFCqJQ5X7puedRx1ef9 +r2rwHlSbi+BUSrF4xn1p0RInkmxTbmwREp/BL97LzfQfN56v+rlc+860dZnMED01jhILkURJ +Ul0KPpGN1ueUwDHyiXF66Ywx+2IGD+0Uqg8aCzikAEzZNRXPmJKlkhMxSHuNzrofx/uq2/J4 +6njV/bZsu/zMPOlbOY4XJSD5KOrwXGdwpDGdfotZayQHKTAi5fRPqUWKcAMMIQfAjOK0nkfm +6tFacjYgBPV46X4BtlpiNYUBAAA= +[end] address@hidden verbatim + address@hidden Output format: + +Revision data in @command{monotone read} compatible packet format. + address@hidden Error conditions: + +If @var{id} is unknown or invalid prints an error message to stderr +and exits with status 1. + address@hidden table + address@hidden monotone automate packet_for_certs @var{id} + address@hidden @strong address@hidden Arguments: + +The @var{id} specifies the revision to output cert packets for. + address@hidden Added in: + +2.0 + address@hidden Purpose: + +Prints the certs associated with a revision in packet format + address@hidden Sample output: + address@hidden +[rcert bdf3b10b5df0f17cc6c1b4b3351d84701bda59ed + branch + address@hidden + bmV0LnZlbmdlLm1vbm90b25l] +K90i1XHHmaMEMuwbPifFweLThJl0m7jigh2Qq6Z7TBwNJ6IMOjXWCizv73cacZ1CtzxFDVwQ +SlqhNWiPQWxdcMp+Uuo+V8IFMKmvxVSTuVDukLMuNAQqpGL5S+a+tEj68NMq+KLKuL8kAAPc +RoFD7GQlTS35S3RHWA4cnvqn+8U= +[end] +[rcert bdf3b10b5df0f17cc6c1b4b3351d84701bda59ed + date + address@hidden + MjAwNi0wNC0wOFQxMTo1MDowMA==] +araz9A8x6AlK6m6UhwnhUhk7cdyxeE2nvzj2gwaDvkaBxOq4SN23/wnaPqUXx1Ddn8smzyRY +HN08xloYc0yNChp3wjbqx20REcsTg3XE4rN/sgCbqqw5hVT22a5ZhqkfkDeoeJvan0R0UBax +ngKYo9eLuABNlmFX2onca75JW1E= +[end] +[rcert bdf3b10b5df0f17cc6c1b4b3351d84701bda59ed + author + address@hidden + bmpzQHBvYm94LmNvbQ==] +BLPOYhgLsAN+w7CwOsv9GfXnG3u7RNF1DTrWdn0AnYE1e+ptgTeMVWUI18H4OGL0B7wm08rv +Pxk/hvsb8fBn1Kf5HDDO2pbjJ0xVzI9+p+TR0y5jJNZlVSTj+nvtPgvK9NzsdooYWnwlWmJv +bOkAzQcZb8NMh8pbQkdHbR5uzMo= +[end] +[rcert bdf3b10b5df0f17cc6c1b4b3351d84701bda59ed + changelog + address@hidden + MjAwNi0wNC0wOCAgTmF0aGFuaWVsIFNtaXRoICA8bmpzQHBvYm94LmNvbT4KCgkqIG5ldHh4 +L3Jlc29sdmVfZ2V0aG9zdGJ5bmFtZS5jeHggKHJlc29sdmVfaG9zdG5hbWUpOiAjaWZkZWYg +b3V0CglXaW4zMi1pbmNvbXBhdGlibGUgZXJyb3IgcmVwb3J0aW5nIGNhbGwuCg==] +Ncl4L/oEPctzVQixTKA6FrLceeHnLiXfeyeFDNmtUFYg9BMUcjWkeyKmaWknLvOcHortxjto +K6pQ9E8S7zI+TpzFAhssg5a///rFL0+2GJU3t6pcHs6LC0Q4tbqzwKd/5+8GwT1gphbM1wm7 +KuzKthwqD3pp49GbgTrp8iWMTr0= +[end] address@hidden verbatim + address@hidden Output format: + +Cert data in @command{monotone read} compatible packet format. + address@hidden Error conditions: + +If @var{id} is unknown or invalid prints an error message to stderr +and exits with status 1. + address@hidden table + address@hidden monotone automate packet_for_fdata @var{id} + address@hidden @strong address@hidden Arguments: + +The @var{id} specifies the file to output an fdata packet for. + address@hidden Added in: + +2.0 + address@hidden Purpose: + +Prints the file data in packet format + address@hidden Sample output: + address@hidden +[fdata 229c7f621b65f7e4970ae5aaec993812b9daa1d4] +H4sIAAAAAAAA/z2OO27DMBBEe51ioMaNrJzBpQAjTXKBBTW0CJPcgFw6yO1DCkG62Q/em83j +R9vlRez6naPKzh2CwkipXFBJbO8fn7f7HV4LQq4mMYoFzdMYSnMj1xXY/lnuoHt2kB2hQpst +PREPZhaxvvchskIKkdU6xsXWvQsk76MOUquGVolZmmmh0+xxvf7JZ5jCFXbU4KZ1muYkT+Kw +FOez5q6uLuh9+9eoQawhez3Fp+VtHJNkfMmDHfALzWYfcAgBAAA= +[end] address@hidden verbatim + address@hidden Output format: + +File data in @command{monotone read} compatible packet format. + address@hidden Error conditions: + +If @var{id} is unknown or invalid prints an error message to stderr +and exits with status 1. + address@hidden table + address@hidden monotone automate packet_for_fdelta @var{from-id} @var{to-id} + address@hidden @strong address@hidden Arguments: + +The @var{from-id} specifies the file to use as the base of the delta, +and @var{to-id} specifies the file to use as the target of the delta. + address@hidden Added in: + +2.0 + address@hidden Purpose: + +Prints the file delta in packet format + address@hidden Sample output: + address@hidden +[fdelta 597049a62d0a2e6af7df0b19f4945ec7d6458727 + 229c7f621b65f7e4970ae5aaec993812b9daa1d4] +H4sIAAAAAAAA/0WOy0oEMRBF9/mKS2/c9LQg4t5lw+BGf6BIKtNhkpSkKop/b9II7m49OOfu +eHp5dnvEj/SHL0aQ75qFAgcQGmcm5RXKjP3t/eP1ekWUhlTVKGeyJNXNoXU/s27AP8sf7O8D +ZEdSSLd1JMaNKzeysY8ps4Iao4oNjM99eFdQDbMOSldDV8ZC3aSxlxpxufzJF5jANx6oyS2b +c0uhO+OwkpezZhCvK0bf8TVrMLZUo5zi0/I4j4UqPunGA+B+AfHvKEIPAQAA +[end] address@hidden verbatim + address@hidden Output format: + +File delta data in @command{monotone read} compatible packet format. + address@hidden Error conditions: + +If @var{from-id} or @var{to-id} is unknown or invalid prints an error +message to stderr and exits with status 1. + address@hidden table + @end ftable @page