# # # patch "automate.cc" # from [9cafd96d99c92a18a0430ff24863d02bf86ca820] # to [e606921c6c0ce1473d9a6c609e0af956b3d78341] # # patch "monotone.texi" # from [0209ff76041fd586bcefef9534057ab7134976c8] # to [b9451f04c745532614b87858909f13a77f2b607b] # ============================================================ --- automate.cc 9cafd96d99c92a18a0430ff24863d02bf86ca820 +++ automate.cc e606921c6c0ce1473d9a6c609e0af956b3d78341 @@ -636,26 +636,8 @@ namespace // Purpose: Prints a summary of every file or directory found in the // workspace or its associated base manifest. -// Output: basic_io format. For each item, three to six lines are output: +// See monotone.texi for output format description. // -// path "" -// old_node "" "file | directory" -// new_node "" "file | directory" -// fs_type "file | directory | none" -// status "ignored | known | missing | unknown" -// changes "content | content attrs | attrs" -// -// 'fs_type' gives the state of the item in the workspace filesystem. -// -// 'old_node' and 'new_node' give the status of the item in the manifest. -// The 'old_node' and 'new_node' lines are not output if the corresponding -// node state is 'none'. -// -// 'changes' is not output if there are no changes. -// -// FIXME: 'dropped', 'renamed' are not explicitly labeled. -// FIXME: whether an item needs to be committed is not clear. -// // Error conditions: If no workspace book keeping _MTN directory is found, // prints an error message to stderr, and exits with status 1. @@ -756,7 +738,7 @@ AUTOMATE(inventory, N_("[PATH]..."), opt else if (item.old_node.exists && item.new_node.exists && (item.old_node.id != item.new_node.id)) { - // check if this is a cyclic rename or a rename + // check if this is a cyclic rename or a rename // paired with an add / drop if (item.old_path.size() > 0 && item.new_path.size() > 0) @@ -780,12 +762,6 @@ AUTOMATE(inventory, N_("[PATH]..."), opt { if (item.new_node.exists) states.push_back("missing"); - - // FIXME: missing 'else'. For examples, - // see tests/automate_inventory: - // 'original' renamed to 'renamed' - // 'dropped' dropped - // Original output identified these. } else // exists on filesystem { @@ -836,7 +812,7 @@ AUTOMATE(inventory, N_("[PATH]..."), opt if (item.new_node.type == path::file && old_roster.has_node(item.new_node.id)) { file_t old_file = downcast_to_file_t(old_roster.get_node(item.new_node.id)); - + if (item.fs_type == path::file && !(item.fs_ident == old_file->content)) changes.push_back("content"); } ============================================================ --- monotone.texi 0209ff76041fd586bcefef9534057ab7134976c8 +++ monotone.texi b9451f04c745532614b87858909f13a77f2b607b @@ -60,7 +60,7 @@ @top Top @end itemize Please be aware that monotone is a slightly unorthodox version control -tool, and many of its concepts are similar --- but subtly or +tool, and many of its concepts are similar --- but subtly or significantly different --- from concepts with similar names in other version control tools. @@ -244,7 +244,7 @@ @section Versions of files space. In these cases, rather than store @i{complete} copies of each version of a file, we store a compact description of only the @i{changes} which are made between versions. Such a description of -changes is called a @dfn{delta}. +changes is called a @dfn{delta}. Storing deltas between files is, practically speaking, as good as storing complete versions of files. It lets you undo changes from a @@ -300,7 +300,7 @@ @section Versions of trees content. In this way, the manifest collects together the snapshot of the file names and contents you have at this point in time; other snapshots with other manifests can use different names for the same -file, or different contents for the same name. +file, or different contents for the same name. Other entries in the manifest format name directories or store file attrs, which we will cover later. @@ -753,9 +753,9 @@ @section Storage and workflow @ifinfo @smallexample @group - ----------------- ----------------- + ----------------- ----------------- ( ) ( ) - ----------------- --- pull ---> ----------------- + ----------------- --- pull ---> ----------------- | | | | | remote | <--- sync ---> | local | | database | | database | @@ -951,23 +951,23 @@ @section Branches | | +---------+ +---------+ | | - +-----------------+ +-------------------+ - | stable revision | | unstable revision | - +-----------------+ +-------------------+ - | | | | - +-------+ +-------+ +-------+ +-------+ - | | | | + +-----------------+ +-------------------+ + | stable revision | | unstable revision | + +-----------------+ +-------------------+ + | | | | + +-------+ +-------+ +-------+ +-------+ + | | | | +-------------+ +--------------+ +---------------+ +----------------+ | left stable | | right stable | | left unstable | | right unstable | | child | | child | | child | | child | +-------------+ +--------------+ +---------------+ +----------------+ - | | | | - +-------+ +--------+ +-------+ +--------+ - | | | | - +----------------+ +------------------+ - | merged stable | | merged unstable | - | revision | | revision | - +----------------+ +------------------+ + | | | | + +-------+ +--------+ +-------+ +--------+ + | | | | + +----------------+ +------------------+ + | merged stable | | merged unstable | + | revision | | revision | + +----------------+ +------------------+ \_____________ _______________/ \_______________ _________________/ \/ \/ @@ -1003,7 +1003,7 @@ @section Branches +-------------+ | | left child | | +-------------+ | - | | + | | *************|****************|************ * | | * * +-----------------+ +-------------+ * @@ -1011,7 +1011,7 @@ @section Branches * +-----------------+ +-------------+ * (before the merge) * | | * *************|****************|************ - | | + | | +--------+ +---+ | | +-----------------+ @@ -1359,14 +1359,14 @@ @section Starting a New Project Notice that Jim has changed his current directory to his newly created workspace. For the rest of this example we will assume that everyone -issues all further monotone commands from their workspace +issues all further monotone commands from their workspace directories. @page @node Adding Files @section Adding Files -Next Jim decides to add some files to the project. He writes up +Next Jim decides to add some files to the project. He writes up a file containing the prototypes for the JuiceBot 7: @smallexample @@ -1398,7 +1398,7 @@ @section Adding Files $ cat >src/apple.c #include "jb.h" -void +void dispense_apple_juice() @{ /* Fill this in please, Abe. */ @@ -1407,7 +1407,7 @@ @section Adding Files $ cat >src/banana.c #include "jb.h" -void +void dispense_banana_juice() @{ /* Fill this in please, Beth. */ @@ -1481,18 +1481,18 @@ @section Adding Files @smallexample @group $ mtn diff -# +# # old_revision [] -# +# # add_file "include/jb.h" # content [3b12b2d0b31439bd50976633db1895cff8b19da0] -# +# # add_file "src/apple.c" # content [2650ffc660dd00a08b659b883b65a060cac7e560] -# +# # add_file "src/banana.c" # content [e8f147e5b4d5667f3228b7bba1c5c1e639f5db9f] -# +# ============================================================================ --- include/jb.h +++ include/jb.h 3b12b2d0b31439bd50976633db1895cff8b19da0 @@ -1516,7 +1516,7 @@ @section Adding Files @@ -0,0 +1,7 @@ +#include "jb.h" + -+void ++void +dispense_apple_juice() address@hidden + /* Fill this in please, Abe. */ @@ -1527,7 +1527,7 @@ @section Adding Files @@ -0,0 +1,7 @@ +#include "jb.h" + -+void ++void +dispense_banana_juice() address@hidden + /* Fill this in please, Beth. */ @@ -1729,7 +1729,7 @@ @section Basic Network Service @end group @end smallexample -This command starts monotone listening on all network interfaces of +This command starts monotone listening on all network interfaces of his laptop on the default port 4691, serving everything in his database. @page @@ -1817,20 +1817,20 @@ @section Making Changes @smallexample @group $ mtn diff -# +# # old_revision [2e24d49a48adf9acf3a1b6391a080008cbef9c21] -# +# # patch "src/apple.c" # from [2650ffc660dd00a08b659b883b65a060cac7e560] # to [e2c418703c863eabe70f9bde988765406f885fd0] -# +# ============================================================================ --- src/apple.c 2650ffc660dd00a08b659b883b65a060cac7e560 +++ src/apple.c e2c418703c863eabe70f9bde988765406f885fd0 @@ -1,7 +1,10 @@ #include "jb.h" - - void + + void dispense_apple_juice() @{ - /* Fill this in please, Abe. */ @@ -1842,11 +1842,11 @@ @section Making Changes @end group @end smallexample -Satisfied with his day's work, Abe decides to commit. +Satisfied with his day's work, Abe decides to commit. @smallexample @group -$ mtn commit +$ mtn commit mtn: beginning commit on branch 'jp.co.juicebot.jb7' @end group @end smallexample @@ -1870,7 +1870,7 @@ @section Making Changes MTN: new_manifest [b33cb337dccf21d6673f462d677a6010b60699d1] MTN: MTN: old_revision [2e24d49a48adf9acf3a1b6391a080008cbef9c21] -MTN: +MTN: MTN: patch "src/apple.c" MTN: from [2650ffc660dd00a08b659b883b65a060cac7e560] MTN: to [e2c418703c863eabe70f9bde988765406f885fd0] @@ -2047,29 +2047,29 @@ @section Dealing with a Fork @smallexample @group $ mtn diff -# +# # old_revision [80ef9c9d251d39074d37e72abf4897e0bbae1cfb] # # patch "src/banana.c" # from [7381d6b3adfddaf16dc0fdb05e0f2d1873e3132a] # to [5e6622cf5c8805bcbd50921ce7db86dad40f2ec6] -# +# ============================================================================ --- src/banana.c 7381d6b3adfddaf16dc0fdb05e0f2d1873e3132a +++ src/banana.c 5e6622cf5c8805bcbd50921ce7db86dad40f2ec6 @@ -1,10 +1,15 @@ #include "jb.h" - -+static void + ++static void +shut_off_banana() address@hidden + spoutctl(BANANA_SPOUT, SET_INTR, 0); + spoutctl(BANANA_SPOUT, FLOW_JUICE, 0); address@hidden + - void + void -dispense_banana_juice() -+dispense_banana_juice() ++dispense_banana_juice() @{ + spoutctl(BANANA_SPOUT, SET_INTR, &shut_off_banana); spoutctl(BANANA_SPOUT, FLOW_JUICE, 1); @@ -2102,7 +2102,7 @@ @section Dealing with a Fork Unfortunately, before Beth managed to sync with Jim, Abe had woken up and implemented a similar interrupt-based apple juice dispenser, but his workspace is 70dec..., which is still ``upstream'' of -Beth's. +Beth's. @smallexample @group @@ -2170,7 +2170,7 @@ @section Dealing with a Fork resolve it. After merging, the branch has a single head again, and Jim updates -his workspace. +his workspace. @smallexample @group @@ -2187,7 +2187,7 @@ @section Dealing with a Fork and the chosen target. The result was then written to Jim's workspace. If Jim's workspace had any uncommitted changes in it, they would have been merged with the update in exactly the same manner as the merge of multiple -committed heads. +committed heads. Monotone makes very little distinction between a ``pre-commit'' merge (an update) and a ``post-commit'' merge. Both sorts of merge use the @@ -2378,7 +2378,7 @@ @section Network Service Revisited Jim decides it's time for a permanent server they can all sync with; 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. +friends and making sure that they have their servers running. Jim has rented some web server space on a service provider's shared system for the JuiceBot Inc. public website, @code{www.juicebot.co.jp}; @@ -2386,7 +2386,7 @@ @section Network Service Revisited server too. He sets up a new monotone database on the server, generates a new key specially for the server (so he doesn't have to expose his own development private key on the shared system), and loads -in the team-members' keys: +in the team-members' keys: @smallexample @group @@ -2483,7 +2483,7 @@ @section Network Service Revisited @smallexample @group $ mtn list vars -database: default-exclude-pattern +database: default-exclude-pattern database: default-include-pattern jp.co.juicebot.jb7* database: default-server jim-laptop.juicebot.co.jp known-servers: jim-laptop.juicebot.co.jp 9e9e9ef1d515ad58bfaa5cf282b4a872d8fda00c @@ -2506,7 +2506,7 @@ @section Network Service Revisited them working as they did before: @itemize @item -The team members can still sync with each other if needed. +The team members can still sync with each other if needed. Hopefully, their new server won't ever be down, but sometimes they might be working together while away from ready network access --- fixing up @@ -2516,7 +2516,7 @@ @section Network Service Revisited @item The team members continue to discover multiple heads and changes that need merging, as before. Each team member can merge the heads, and will -produce the same revision id if they merge to the same result. +produce the same revision id if they merge to the same result. They now develop a new habit out of courtesy, though --- they try not to leave multiple heads and unmerged changes on the server, at least not @@ -2541,7 +2541,7 @@ @section Network Service Revisited @item In fact, Jim realises that he can now commit a copy of the web site's current contents into monotone on a new branch, address@hidden, and keep a backup of that content too. address@hidden, and keep a backup of that content too. Now he can use monotone to work on the website offline, and let other team members add and edit the content; he can also preview changes @@ -2557,7 +2557,7 @@ @section Network Service Revisited server and tamper with the database, they won't be able to inject malicious code into the project, because all revisions are signed by the team members, and he has set his @ref{Trust Evaluation Hooks} so he -doesn't trust the server key for signing revisions. +doesn't trust the server key for signing revisions. In monotone, the important trust consideration is on the @emph{signed content}, rather than on the @emph{replication path} by which that @@ -2607,7 +2607,7 @@ @section Other Transports to convert that URI into a @dfn{connection command}. If the Lua hook returns a connection command, monotone spawns the command locally and speaks netsync over a pipe connected to the command's standard I/O -handles. +handles. If the Lua hook does not return a connection command, monotone attempts to parse the command-line argument as a TCP address -- a @@ -2617,12 +2617,12 @@ @section Other Transports By default, monotone understands two URI schemes: @enumerate address@hidden SSH URIs, of the form address@hidden SSH URIs, of the form @code{ssh://address@hidden@@address@hidden:@var{port}]/@var{path/to/db.mtn}}, to synchronize between private databases on hosts accessible only through SSH. (These paths are absolute; to refer to a path relative to a home directory, use - @code{ssh://@var{host-part}/~/@var{relative/path.mtn}} or + @code{ssh://@var{host-part}/~/@var{relative/path.mtn}} or @code{ssh://@var{host-part}/address@hidden/@var{relative/path.mtn}}.) @item File URIs, of the form @code{file:@var{/path/to/db.mtn}}, to synchronize between local databases. @@ -2635,8 +2635,8 @@ @section Other Transports SSH connection. You will need @command{mtn} to be in the command execution path of the remote shell environment. -In the case of File URIs, @command{mtn} is run locally, so must be -in your command execution path. +In the case of File URIs, @command{mtn} is run locally, so must be +in your command execution path. In both cases, the database specified in the URI needs to exist already, and will be locked for the duration of the synchronization @@ -2715,9 +2715,9 @@ @heading Selectors in detail value recorded in your _MTN/options file. @item Heads selection Uses selector type @code{h}. For example, @code{h:net.venge.monotone} matches address@hidden certs where the cert value is @code{net.venge.monotone} and address@hidden certs where the cert value is @code{net.venge.monotone} and the associated revision is a head revision on that branch. Values to match -for can have shell wildcards like the branch selector. If you give a bare +for can have shell wildcards like the branch selector. If you give a bare @code{h:} monotone will require you to be in a workspace, and use the branch recorded in your _MTN/options file. @item Date selection @@ -2745,7 +2745,7 @@ @heading Selectors in detail Values to match for can have shell wildcards. @end table -Further selector types may be added in the future. +Further selector types may be added in the future. @heading Composite selectors @@ -2786,7 +2786,7 @@ @heading Expanding dates time 00:00:00 @item @{minute|address@hidden Expands to today date and time, minus the specified @code{number} of -minutes|hours. +minutes|hours. @item @{day|week|month|address@hidden Expands to today date, minus the specified @code{number} of days|weeks|months|years. @code{e} and @code{l} selectors assume time @@ -2890,7 +2890,7 @@ @heading Finding a workspace directory is done by traversing parent directories until an @file{_MTN} directory is found or the filesystem root is reached. Upon finding an @file{_MTN} directory, the @file{_MTN/options} file is read for -default options. The @option{--root} option may be used to stop the +default options. The @option{--root} option may be used to stop the search early, before reaching the root of the physical filesystem. Many monotone commands don't require a workspace and will simply @@ -3021,7 +3021,7 @@ @section Workspace Collisions If some other program is creating files in the workspace at the same time as monotone, the colliding file might be created after the collision check at the start. address@hidden address@hidden Other kinds of unpredictable system errors, like permissions problems or disk full conditions, might cause failures when monotone is rearranging the workspace content. @@ -3115,7 +3115,7 @@ @section Quality Assurance the @code{testresult} certs present on the source and proposed destination of an update. Only if the change in test results are deemed ``acceptable'' does monotone actually select an update target -to merge into your workspace. +to merge into your workspace. For details on these hooks, see the @ref{Hook Reference}. @@ -3195,7 +3195,7 @@ @section Reserved Files Control files contain special content formatted for use by monotone. Versioned files are recorded in a monotone database and have -their state tracked as they are modified. +their state tracked as they are modified. If a control file is versioned, it is considered @emph{part of} the state of the workspace, and will be recorded as a manifest @@ -3253,7 +3253,7 @@ @heading Existing control files is committed, the base revision is considered to be the ancestor of the committed revision. @item _MTN/options -Contains ``sticky'' command-line options such as @option{--db} or +Contains ``sticky'' command-line options such as @option{--db} or @option{--branch}, such that you do not need to enter them repeatedly after checking out a particular workspace. @item _MTN/log @@ -3332,7 +3332,7 @@ @section Reserved Certs @item tag This cert's value is a symbolic name given to a revision, which may be used as a way of selecting the revision by name for later commands like address@hidden, @command{log} or @command{diff}. address@hidden, @command{log} or @command{diff}. @item testresult This cert's value is interpreted as a boolean string, either @code{0} @@ -3359,7 +3359,7 @@ @section Naming Conventions We therefore recommend two naming conventions: @itemize address@hidden address@hidden For @sc{rsa} keys, use the name of an active email address you own. This will minimize conflicts, and also serves as a mnemonic to associate your personal @emph{identity} with signatures made with your @@ -3433,24 +3433,24 @@ @section Merging @code{manual_merge} attribute for that file is present and @code{true}. In automatic mode files are merged without user intervention, using -monotone internal three-way merging algorithm. +monotone internal three-way merging algorithm. Only if there are conflicts or an ancestor is not available monotone switches to manual mode, essentially escalating the merging to the user. When working in manual mode, monotone invokes the @code{merge3} hook -to start an user defined external merge tool. +to start an user defined external merge tool. If the tool terminates without writing the merged file, monotone aborts the merging, reverting any changes made. By redefining the aforementioned hooks the user can not only choose a preferred merge tool, but even select different programs for different file types. For example, gimp for .png files, OpenOffice.org for -.doc, and so on. +.doc, and so on. Starting with monotone 0.20, the @code{manual_merge} attribute is automatically set at add time for all ``binary'' files, i.e. all files -for which the @code{binary_file} hook returns true. +for which the @code{binary_file} hook returns true. Currently, this means all files with extension gif, jpeg, png, bz2, gz and zip, plus files containing at least one of the following bytes: - + @smallexample @group 0x00 thru 0x06 @@ -3462,7 +3462,7 @@ @section Merging The attribute could also be manually forced or removed using the appropriate monotone commands. Remember that monotone switches to manual merging even if only one of -the files to be merged has the @code{manual_merge} attribute set. +the files to be merged has the @code{manual_merge} attribute set. @page @node Migrating and Dumping @@ -3496,7 +3496,7 @@ @section Migrating and Dumping plain text version of your database on hand, the @command{mtn db dump} command can produce a plain ASCII SQL statement which generates the state of your database. This dump can later be reloaded using the address@hidden db load} command. address@hidden db load} command. Note that when reloading a dumped database, the schema of the dumped database is @emph{included} in the dump, so you should not try to @@ -3509,7 +3509,7 @@ @section Importing from CVS Monotone is capable of reading CVS files directly and importing them into a database. This feature is still somewhat immature, but moderately large ``real world'' CVS trees on the order of 1GB have -successfully been imported. +successfully been imported. Note however that the machine requirements for CVS trees of this size are not trivial: it can take several hours on a modern system to @@ -3521,7 +3521,7 @@ @section Importing from CVS @itemize @item Your domain name, @code{example.net} in this example. address@hidden address@hidden Your key name, @code{import@@example.net} in this example. @item Your project name, @code{wobbler} in this example. @@ -4075,7 +4075,7 @@ @heading Initializing a Repository @tab @smallexample @group -$ mtn db init --db=/path/to/database.mtn +$ mtn db init --db=/path/to/database.mtn @end group @end smallexample @end multitable @@ -4116,8 +4116,8 @@ @section Tree Write the contents of a specific file @var{path} to standard output. -Without a @option{--revision} argument, the command outputs the -contents of @var{path} as found in the current revision. This requires +Without a @option{--revision} argument, the command outputs the +contents of @var{path} as found in the current revision. This requires the command be executed from within a workspace. With an explicit @option{--revision} argument, the command outputs @@ -4188,17 +4188,17 @@ @section Tree will show up as a new head and thus a subsequent @command{merge} will incorporate the inverse of the disapproved changes in the other head(s). -Conceptually, @command{disapprove}s contract is that disapprove(A) gives a -revision B such that whenever B is merged with a descendant D of A the merge +Conceptually, @command{disapprove}s contract is that disapprove(A) gives a +revision B such that whenever B is merged with a descendant D of A the merge will result in what D ``would have looked like'' if A had never happened. -Note that as a consequence of this contract the @command{disapprove} command -only works if @var{id} has exactly one ancestor, since it hasn't been +Note that as a consequence of this contract the @command{disapprove} command +only works if @var{id} has exactly one ancestor, since it hasn't been worked out how to generate such a descendant in the multi-ancestor case. @item mtn heads address@hidden -This command lists the ``heads'' of @var{branchname}. +This command lists the ``heads'' of @var{branchname}. The ``heads'' of a branch is the set of revisions which are members of the branch, but which have no descendants. These revisions are @@ -4370,10 +4370,10 @@ @section Workspace @itemx mtn ci address@hidden @itemx mtn commit @var{pathname...} @itemx mtn ci @var{pathname...} address@hidden mtn commit address@hidden address@hidden @var{pathname...} address@hidden mtn ci address@hidden address@hidden @var{pathname...} address@hidden mtn commit address@hidden @var{pathname...} address@hidden mtn ci address@hidden @var{pathname...} address@hidden mtn commit address@hidden address@hidden @var{pathname...} address@hidden mtn ci address@hidden address@hidden @var{pathname...} address@hidden mtn commit address@hidden @var{pathname...} address@hidden mtn ci address@hidden @var{pathname...} This command looks at your workspace, decides which files have changed, and saves the changes to your database. It does this by @@ -4404,7 +4404,7 @@ @section Workspace changed within the current subdirectory of the workspace. The @option{--message} and @option{--message-file} options are mutually -exclusive. Both provide a @var{logmsg} describing the commit. +exclusive. Both provide a @var{logmsg} describing the commit. @option{--message-file} actually specifies the name of the file containing the log message, while @option{--message} provides it directly. @@ -4431,14 +4431,14 @@ @section Workspace certificates, which it attaches to the new manifest version and copies into your database: @itemize address@hidden address@hidden An @code{author} cert, indicating the person responsible for the changes leading to the new revision. Normally this defaults to your signing key or the return value of the @code{get_author} hook; you may override this by passing the @option{--author} option to commit. This is useful when committing a patch on behalf of someone else, or when importing ``by hand'' from another version control system. address@hidden address@hidden A @code{branch} cert, indicating the branch the committed revision belongs to. @item @@ -4486,7 +4486,7 @@ @section Workspace Remove any candidates which lack acceptable testresult certificates. From the remaining candidates, select the deepest child by ancestry and call it the ``target'' of the update. address@hidden address@hidden Merge the target of the update with the workspace, in memory, and if the merge is successful, write the result over top of the workspace. @end itemize @@ -4622,9 +4622,9 @@ @section Network session is served over the @code{stdin} and @code{stdout} file descriptors. If @option{--no-transport-auth} is provided along with @option{--stdio}, transport authentication and access control mechanisms -are disabled. Only use @option{--no-transport-auth} if you are certain -that the transport channel in use already provides sufficient -authentication and authorization facilities. +are disabled. Only use @option{--no-transport-auth} if you are certain +that the transport channel in use already provides sufficient +authentication and authorization facilities. The @var{uri-or-address} arguments given to @command{push}, @command{pull}, and @command{sync} can be of two possible forms. If @@ -4714,7 +4714,7 @@ @section Informative This command prints a description of the ``status'' of your workspace. In particular, it prints: @itemize address@hidden address@hidden The branch currently selected in @file{_MTN/options} for the workspace. @item @@ -4754,8 +4754,8 @@ @section Informative revision in forward-ancestry order. This is useful to review changes that will be applied to the workspace when @command{update} is run. -If @address@hidden is given, the command starts tracing back through -history from these revisions, otherwise it starts from the base revision of +If @address@hidden is given, the command starts tracing back through +history from these revisions, otherwise it starts from the base revision of your workspace. If @address@hidden is given, log will only print entries for revisions @@ -4779,14 +4779,14 @@ @section Informative @item mtn annotate @var{file} @itemx mtn annotate address@hidden [--brief] @var{file} -Dumps an annotated copy of the file to stdout. In the absence of the +Dumps an annotated copy of the file to stdout. In the absence of the @option{--brief} flag, each line of the file is translated to : in the output, where is the revision in which that line of the file was last edited. If @option{--brief} is specified, the output is in the form .. by : -Only the first 8 characters of the revision id are displayed, the +Only the first 8 characters of the revision id are displayed, the author cert value is truncated at the first @code{@@} or space character and the date field is truncated to remove the time of day. @@ -4814,7 +4814,7 @@ @section Informative completion systems, such as those in @command{bash} and @command{zsh}. The complete command for keys and revisions have a @option{--verbose} option. -Programmable completion systems can use @option{--verbose} output to +Programmable completion systems can use @option{--verbose} output to present users with additional information about each completion option. For example, verbose output for @code{revision} looks like this: @@ -4911,9 +4911,9 @@ @section Informative Whether the signature on the certificate is @code{ok} or @code{bad} @item The key ID of the signer of the certificate address@hidden address@hidden The name of the certificate address@hidden address@hidden The value of the certificate @end itemize @@ -5008,7 +5008,7 @@ @section Informative @itemx mtn list unknown @var{pathname...} @itemx mtn ls unknown @var{pathname...} -This command lists all files in your workspace that monotone is +This command lists all files in your workspace that monotone is either ignoring or knows nothing about. Specifying pathnames to the @command{list unknown} command restricts the @@ -5169,7 +5169,7 @@ @section Certificate @section Certificate @ftable @command address@hidden mtn cert @var{id} @var{certname} address@hidden mtn cert @var{id} @var{certname} @itemx mtn cert @var{id} @var{certname} @var{certval} These commands create a new certificate with name @var{certname}, for a @@ -5200,7 +5200,7 @@ @section Certificate This command associates the symbolic name @var{tagname} with the revision @var{id}, so that symbolic name can later be used in @ref{Selectors} for specifying revisions for commands like address@hidden or @command{diff}. address@hidden or @command{diff}. This command is a synonym for @command{mtn cert @var{id} tag @var{tagname}}. @@ -5290,21 +5290,21 @@ @section Database Deletes any value associated with @var{name} in @var{domain}. See @ref{Vars} for more information. address@hidden mtn db init address@hidden address@hidden mtn db init address@hidden This command initializes a new monotone database at @var{dbfile}. address@hidden mtn db info address@hidden address@hidden mtn db info address@hidden This command prints information about the monotone database @var{dbfile}, including its schema version and various table size statistics. address@hidden mtn db version address@hidden address@hidden mtn db version address@hidden This command prints out just the schema version of the monotone database @var{dbfile}. address@hidden mtn db dump address@hidden address@hidden mtn db dump address@hidden This command dumps an SQL statement representing the entire state of @var{dbfile} to the standard output stream. It is a very low-level @@ -5312,7 +5312,7 @@ @section Database possible. It is sometimes also useful when migrating databases between variants of the underlying SQLite database format. address@hidden mtn db load address@hidden address@hidden mtn db load address@hidden This command applies a raw SQL statement, read from the standard input stream, to the database @var{dbfile}. It is most useful when loading @@ -5322,7 +5322,7 @@ @section Database database is @emph{included} in the dump, so you should not try to @command{init} your database before a @command{load}. address@hidden mtn db migrate address@hidden address@hidden mtn db migrate address@hidden This command attempts to migrate the database @var{dbfile} to the newest schema known by the version of monotone you are currently @@ -5333,7 +5333,7 @@ @section Database a copy of it before migrating, in case there is an untrapped error during migration. address@hidden mtn db check address@hidden address@hidden mtn db check address@hidden Monotone always works hard to verify the data it creates and accesses. For instance, if you have hard drive problems that corrupt data in @@ -5349,7 +5349,7 @@ @section Database @itemize address@hidden missing files address@hidden missing files that are referenced by their @sc{sha1} hash from some manifest but do not exist in the database. This is a serious problem; it means that your history is not fully reconstructible. You can fix it by finding the @@ -6252,228 +6252,344 @@ @section Automation @table @strong @item Arguments: -None. +A file path (optional). address@hidden FIXME: what does this mean? @item Added in: -1.0 +4.1 (non basic_io version added in 1.0) address@hidden FIXME: check this number when merge to main branch @item Purpose: Prints the inventory of every file found in the workspace or its -associated base manifest. Each unique path is listed on a line prefixed by -three status characters and two numeric values used for identifying -renames. +associated base and revision manifests. Each unique path is +listed in a basic_io stanza. Stanzas are separated by blank lines. @item Sample output: -All basic status codes: +All basic status cases: address@hidden + path "added" +new_type "file" + fs_type "file" + status "added" "known" address@hidden - M 0 0 missing - AP 0 0 added -D 0 0 dropped -R 1 0 renamed-from-this - R 0 1 renamed-to-this - P 0 0 patched - 0 0 unchanged - U 0 0 unknown - I 0 0 ignored + path "dropped" +old_type "file" + fs_type "none" + status "dropped" + + path "ignored~" +fs_type "file" + status "ignored" + + path "missing" +old_type "file" +new_type "file" + fs_type "none" + status "missing" + + path "original" +old_type "file" +new_path "renamed" + fs_type "none" + status "rename_source" + + path "patched" +old_type "file" +new_type "file" + fs_type "file" + status "known" + changes "content" + + path "renamed" +new_type "file" +old_path "original" + fs_type "file" + status "rename_target" "known" + + path "unchanged" +old_type "file" +new_type "file" + fs_type "file" + status "known" + + path "unknown" +fs_type "file" + status "unknown" @end verbatim -Two files swapped: +Two files swapped in both the revision manifest and the workspace: address@hidden + path "original" +old_type "file" +new_path "unchanged" +new_type "file" +old_path "unchanged" + fs_type "file" + status "rename_source" "rename_target" "known" address@hidden -RR 1 2 unchanged -RR 2 1 original + path "unchanged" +old_type "file" +new_path "original" +new_type "file" +old_path "original" + fs_type "file" + status "rename_source" "rename_target" "known" @end verbatim -Recorded with monotone that two files were swapped, but they were not -actually swapped in the filesystem. Thus they both appear as patched: - +Recorded in the revision manifest that two files were swapped, but +they were not actually swapped in the workspace. Thus they both appear +as patched: @verbatim -RRP 1 2 unchanged -RRP 2 1 original address@hidden verbatim + path "original" +old_type "file" +new_path "unchanged" +new_type "file" +old_path "unchanged" + fs_type "file" + status "rename_source" "rename_target" "known" + changes "content" -Rename @file{foo} to @file{bar}; add new file @file{foo}: + path "unchanged" +old_type "file" +new_path "original" +new_type "file" +old_path "original" + fs_type "file" + status "rename_source" "rename_target" "known" + changes "content" address@hidden -RAP 1 0 foo - R 0 1 bar @end verbatim -Rotated files @file{foo} -> @file{bar} -> @file{baz} -> @file{foo}: +Rename (in the manifest and the workspace) @file{foo} to @file{bar}; +add (in the manifest and the workspace) new file @file{foo}: address@hidden + path "foo" +old_type "file" +new_path "bar" +new_type "file" + fs_type "file" + status "rename_source" "added" "known" + path "bar" +new_type "file" +old_path "foo" + fs_type "file" + status "rename_target" "known" address@hidden verbatim + +Rotated files @file{foo} -> @file{bar} -> @file{baz} -> @file{foo} (in +the manifest and the workspace): @verbatim -RR 1 3 foo -RR 2 1 bar -RR 3 2 baz address@hidden verbatim + path "foo" +old_type "file" +new_path "bar" +new_type "file" +old_path "baz" + fs_type "file" + status "rename_source" "rename_target" "known" -Recorded the rotation of files @file{foo} -> @file{bar} -> @file{baz} -> address@hidden, but the actual files in the workspace were not -moved, so monotone interprets all files as having been patched: + path "bar" +old_type "file" +new_path "baz" +new_type "file" +old_path "foo" + fs_type "file" + status "rename_source" "rename_target" "known" address@hidden -RRP 1 3 foo -RRP 2 1 bar -RRP 3 2 baz + path "baz" +old_type "file" +new_path "foo" +new_type "file" +old_path "bar" + fs_type "file" + status "rename_source" "rename_target" "known" @end verbatim -Dropped but not removed and thus unknown: - +Recorded in the revison manifest the rotation of files @file{foo} -> address@hidden -> @file{baz} -> @file{foo}, but the actual files in the +workspace were not moved, so monotone interprets all files as having +been patched: @verbatim -D U 0 0 dropped address@hidden verbatim + path "foo" +old_type "file" +new_path "bar" +new_type "file" +old_path "baz" + fs_type "file" + status "rename_source" "rename_target" "known" + changes "content" -Added a non-existent file which is thus missing: + path "bar" +old_type "file" +new_path "baz" +new_type "file" +old_path "foo" + fs_type "file" + status "rename_source" "rename_target" "known" + changes "content" address@hidden - AM 0 0 added + path "baz" +old_type "file" +new_path "foo" +new_type "file" +old_path "bar" + fs_type "file" + status "rename_source" "rename_target" "known" + changes "content" @end verbatim -Recorded a rename, but not moved in the filesystem, and thus unknown -source and missing target: +Dropped from the manifest but not removed in the workspace and thus +unknown: address@hidden + path "dropped" +old_type "file" + fs_type "file" + status "dropped" "unknown" address@hidden verbatim +Added in the manifest but not in the workspace, and thus missing: @verbatim -R U 1 0 original - RM 0 1 renamed + path "added" +new_type "file" + fs_type "none" + status "added" "missing" @end verbatim -Moved in the filesystem but no rename recorded, and thus missing source -and unknown target: +Recorded a rename in the manifest, but not moved in the workspace, +and thus unknown source and missing target: address@hidden + path "original" +old_type "file" +new_path "renamed" + fs_type "file" + status "rename_source" "unknown" + path "renamed" +new_type "file" +old_path "original" + fs_type "none" + status "rename_target" "missing" address@hidden verbatim + +Moved in the workspace but no rename recorded in the manifest, and +thus missing source and unknown target: @verbatim - M 0 0 original - U 0 0 renamed address@hidden verbatim + path "original" +old_type "file" +new_type "file" + fs_type "none" + status "missing" -Renamed and patched: + path "renamed" +fs_type "file" + status "unknown" address@hidden verbatim +Renamed in the manifest and the workspace and patched: @verbatim -R 1 0 original - RP 0 1 renamed + path "original" +old_type "file" +new_path "renamed" + fs_type "none" + status "rename_source" + + path "renamed" +new_type "file" +old_path "original" + fs_type "file" + status "rename_target" "known" + changes "content" @end verbatim @item Output format: -Each path is printed on its own line, prefixed by three status -characters described below. The status is followed by a single space and -two numbers, each separated by a single space, used for identifying renames. -The numbers are followed by a single space and then the pathname, which -includes the rest of the line. Directory paths are identified as ending with -the "/" character, file paths do not end in this character. +Each path is printed in one basic_io stanza. Stanzas are separated by +a blank line. Each stanza starts with a @code{path} line, and contains +up to seven lines. The order of the lines is not important, and may +change in future revisions, except that the first line will always be address@hidden -The three status characters are as follows. address@hidden @option address@hidden 'path' +the file or directory path, relative to the workspace root. The file +either exists in the workspace, or is listed in the base or revision +manifest. address@hidden -column 1 pre-state - ' ' the path was unchanged in the pre-state - 'D' the path was deleted from the pre-state - 'R' the path was renamed from the pre-state name -column 2 post-state - ' ' the path was unchanged in the post-state - 'R' the path was renamed to the post-state name - 'A' the path was added to the post-state -column 3 file-state - ' ' the file is known and unchanged from the current manifest version - 'P' the file is patched to a new version - 'U' the file is unknown and not included in the current manifest - 'I' the file is ignored and not included in the current manifest - 'M' the file is missing but is included in the current manifest address@hidden verbatim address@hidden old_type +gives the type of the file in the base manifest. ``type'' is +either @option{file}, @option{directory}, or @option{none}. address@hidden is output only if it is different from the type in +the revision manifest or workspace. -Note that out of the 45 possible status code combinations, only 26 are valid, -detailed below. address@hidden new_type +the type of the file in the revision manifest. @option{new_type} is +output only if it is different from the type in the base manifest or +workspace. address@hidden -' ' unchanged -' P' patched (contents changed) -' U' unknown (exists on the filesystem but not tracked) -' I' ignored (exists on the filesystem but excluded by Lua hook) -' M' missing (exists in the manifest but not on the filesystem) address@hidden fs_type +the type of the file in the workspace (also called the filesystem). address@hidden is always output. -' A ' added (invalid, add should have associated patch) -' AP' added and patched -' AU' added but unknown (invalid) -' AI' added but ignored (invalid, added files are no longer ignored) -' AM' added but missing from the filesystem address@hidden old_path +the old path for the file, if it has been renamed in the revision +manifest. -' R ' rename target -' RP' rename target and patched -' RU' rename target but unknown (invalid) -' RI' rename target but ignored (invalid) -' RM' rename target but missing from the filesystem address@hidden new_path +the new path for the file, if it has been renamed in the revision +manifest. -'D ' dropped -'D P' dropped and patched (invalid) -'D U' dropped and unknown (still exists on the filesystem) -'D I' dropped and ignored -'D M' dropped and missing (invalid) address@hidden status address@hidden is always output. Its value is one or more of: -'DA ' dropped and added (invalid, add should have associated patch) -'DAP' dropped and added and patched -'DAU' dropped and added but unknown (invalid) -'DAI' dropped and added but ignored (invalid, added files are no longer ignored) -'DAM' dropped and added but missing from the filesystem address@hidden @option address@hidden rename_source +the old name of a file that has been renamed. -'DR ' dropped and rename target -'DRP' dropped and rename target and patched -'DRU' dropped and rename target but unknown (invalid) -'DRI' dropped and rename target but ignored (invalid) -'DRM' dropped and rename target but missing from the filesystem address@hidden rename_target +the new name of a file that has been renamed. -'R ' rename source -'R P' rename source and patched (invalid) -'R U' rename source and unknown (still exists on the filesystem) -'R I' rename source and ignored -'R M' rename source and missing (invalid) address@hidden added +the file is new in the revision manifest (not in the base +manifest). -'RA ' rename source and added (invalid, add should have associated patch) -'RAP' rename source and added and patched -'RAU' rename source and added but unknown (invalid) -'RAI' rename source and added but ignored (invalid, added files are no longer ignored) -'RAM' rename source and added but missing from the filesystem address@hidden dropped +the file is deleted in the revision manifest and the workspace. -'RR ' rename source and target -'RRP' rename source and target and target patched -'RRU' rename source and target and target unknown (invalid) -'RRI' rename source and target and target ignored (invalid) -'RRM' rename source and target and target missing address@hidden verbatim address@hidden missing +the file is deleted in the workspace but not the revision manifest. -The two numbers are used to match up the pre-state and post-state of a -rename. Imagine a situation where there are two renames. address@hidden inventory} will print something like: address@hidden ignored +the file is ignored by monotone. address@hidden -R 1 0 a -R 2 0 b - R 0 2 c - R 0 1 d address@hidden verbatim address@hidden known +the file exists in the workspace, and in the revision manifest. -Here the status characters tell us that @file{a} and @file{b} were -renamed, and we can tell that one was renamed to @file{c} and one was -renamed to @file{d}, but we can't tell which was renamed to which. To -do that, we have to refer to the numbers. The numbers do not themselves -mean anything; their only purpose is to let you match up the two -``ends'' of a rename. The 1 in the left column by @file{a} means that address@hidden was the source of a rename, and the 1 in the right column by address@hidden means that @file{d} was the target of that same rename. -Similarly, the two 2's tell us that @file{b} was renamed to @file{c}. address@hidden unknown +the file exists in the workspace, but not in the revision manifest. -There are two columns of numbers because the same file can -simultaneously be the target and source of a rename. The number '0' is -used as a meaningless placeholder in all cases where a file is not a -source or target of a rename. Any non-zero number that occurs at all -will occur exactly once in the first column and exactly once in the -second column. address@hidden invalid +the file exists in the workspace and revision manifest, but with +different types (one is a directory, the other a file). address@hidden FIXME: not shown in examples or tests address@hidden table address@hidden changes + @table @option + @item content + the file contents have changed. + + @item attrs + the file attributes have changed. + + @end table address@hidden table + Full support for versioned directories is not yet complete and the inventory will only list entries for renamed or dropped -directories. +directories. @c FIXME: is this true? @item Error conditions: @@ -6496,14 +6612,13 @@ @section Automation @item Purpose: Prints all certificates associated with the given revision ID. -Each certificate is contained in a basic IO stanza. For each certificate, +Each certificate is contained in a basic IO stanza. For each certificate, the following values are provided: - @verbatim 'key' a string indicating the key used to sign this certificate. 'signature' - a string indicating the status of the signature. Possible + a string indicating the status of the signature. Possible values of this string are: 'ok' : the signature is correct 'bad' : the signature is invalid @@ -6518,7 +6633,7 @@ @section Automation 'trusted' : this certificate is trusted 'untrusted' : this certificate is not trusted @end verbatim - + @item Sample output: @verbatim @@ -6551,14 +6666,14 @@ @section Automation @item Output format: -All stanzas are formatted by basic_io. Stanzas are separated -by a blank line. Values will be escaped, '\' to '\\' and +All stanzas are formatted by basic_io. Stanzas are separated +by a blank line. Values will be escaped, '\' to '\\' and '"' to '\"'. @item Error conditions: -If a certificate is signed with an unknown public key, a -warning message is printed to stderr. If the revision specified is unknown +If a certificate is signed with an unknown public key, a +warning message is printed to stderr. If the revision specified is unknown or invalid prints an error message to stderr and exits with status 1. @end table @@ -6643,7 +6758,7 @@ @section Automation is a piece of the output of the command. All but the last packet for a given command will have the - field set to 'm'. + field set to 'm'. @item Error conditions: @@ -6662,8 +6777,8 @@ @section Automation @table @strong @item Arguments: -Specifying the option @var{id} argument outputs the changeset -information for the specified @var{id}. Otherwise, @var{id} is +Specifying the option @var{id} argument outputs the changeset +information for the specified @var{id}. Otherwise, @var{id} is determined from the workspace. @item Added in: @@ -6694,15 +6809,15 @@ @section Automation @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. +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 +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 +Possible values of this first value are along with an ordered list of basic_io formatted stanzas that will be provided are: @verbatim @@ -6747,7 +6862,7 @@ @section Automation format: ('set', filename), ('attr', attr name), ('value', attr value) occurs: zero or more times @end 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. The 'delete' and following stanzas will be grouped under the corresponding 'old_revision' @@ -6941,11 +7056,11 @@ @section Automation 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 +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 +Possible values of this first value are along with an ordered list of basic_io formatted stanzas that will be provided are: @verbatim @@ -6963,7 +7078,7 @@ @section Automation format: ('file', pathname), ('content', file id) occurs: zero or more times @end 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 @@ -7016,8 +7131,8 @@ @section Automation There is one basic_io stanza for each attribute of the given file. -All stanzas are formatted by basic_io. Stanzas are separated -by a blank line and ordered by attribute name. Values will be +All stanzas are formatted by basic_io. Stanzas are separated +by a blank line and ordered by attribute name. Values will be escaped, '\' to '\\' and '"' to '\"'. Each attribute stanza also contains another entry which tells the status @@ -7079,7 +7194,7 @@ @section Automation @item Purpose: Edits the current workspace revision and inserts the given attribute key and -value for the specified path. Note that this change is not committed and +value for the specified path. Note that this change is not committed and therefor behaves exactly like @command{mtn attr set @var{key} @var{value}}. @item Output format: @@ -7108,7 +7223,7 @@ @section Automation Removes an attribute from the current workspace revision for the specified path. If no attribute key is given, all attributes of this path are removed. Note that -this change is not committed and therefor behaves exactly like +this change is not committed and therefor behaves exactly like @command{mtn attr drop @var{path} address@hidden @item Output format: @@ -7137,7 +7252,7 @@ @section Automation @itemize @item -no revision: the diff is done between the workspace revision and the +no revision: the diff is done between the workspace revision and the parent (base) revision of this workspace @item one revision: the diff is done between the workspace revision and the @@ -7156,7 +7271,7 @@ @section Automation Prints the content changes between two revisions or a revision and the current workspace. This command differs from @command{mtn diff} in that way that it only outputs content changes and keeps quite on renames or drops, as the header of address@hidden diff} is omitted (this is what @command{mtn automate get_revision} address@hidden diff} is omitted (this is what @command{mtn automate get_revision} already provides). @item Sample output: @@ -7182,7 +7297,7 @@ @section Automation @item Error conditions: If more than two revisions are given or a workspace is required, but -not found, prints to stderr and exits with status 1. If one or more file +not found, prints to stderr and exits with status 1. If one or more file restrictions can't be applied, the command prints to stderr and exits as well. @end table @@ -7570,7 +7685,7 @@ @section Automation @item Arguments: The @var{source_id} specifies a revision ID in which @var{file} is current extant. -and @var{file} specifies the file whose name in @var{target_id} is to be determined; +and @var{file} specifies the file whose name in @var{target_id} is to be determined; @var{target_id} specifies a revision ID. @item Added in: @@ -7579,9 +7694,9 @@ @section Automation @item Purpose: -Given a the file name @var{file} in the source revision @var{source_id}, a filename -will if possible be returned naming the file in the target revision @var{target_id}. -This allows the same file to be matched between revisions, accounting +Given a the file name @var{file} in the source revision @var{source_id}, a filename +will if possible be returned naming the file in the target revision @var{target_id}. +This allows the same file to be matched between revisions, accounting for renames and other changes. @item Sample output: @@ -7603,18 +7718,18 @@ @section Automation @item Error conditions: If the revision IDs @var{source_id} or @var{target_id} are unknown or invalid prints an error -message to stderr and exits with status 1. If the file path @var{file} does not exist in the -revision @var{source_id} or is invalid, prints an error message to stderr and exits with status +message to stderr and exits with status 1. If the file path @var{file} does not exist in the +revision @var{source_id} or is invalid, prints an error message to stderr and exits with status 1. Note that @var{file} not existing in the revision @var{target_id} is not an error. @end table @item mtn automate db_get @var{domain} @var{name} address@hidden @strong address@hidden @strong @item Arguments: -The @var{domain} and @var{name} specify the database variable +The @var{domain} and @var{name} specify the database variable which is returned. @item Added in: @@ -7627,13 +7742,13 @@ @section Automation @item Sample output: address@hidden -off.net address@hidden +off.net @end verbatim @item Output format: -Exactly the variable's content. Since this command is mainly intended for +Exactly the variable's content. Since this command is mainly intended for @command{automate stdio} it will not add a trailing newline. @item Error conditions: @@ -7648,7 +7763,7 @@ @section Automation @table @strong @item Arguments: -The @var{domain} and @var{name} specify the database variable +The @var{domain} and @var{name} specify the database variable which is changed to @var{value}. @item Added in: @@ -7661,8 +7776,8 @@ @section Automation @item Sample usage: address@hidden -mtn automate db_set database default-server off.net address@hidden +mtn automate db_set database default-server off.net @end verbatim @item Output format: @@ -7677,7 +7792,7 @@ @section Automation @item mtn automate put_file address@hidden @var{contents} address@hidden @strong address@hidden @strong @item Arguments: The optional @var{base-id} specifies a file-id on which the contents are @@ -7690,14 +7805,14 @@ @section Automation @item Purpose: -Preparation of a workspace-less commit. -See also @command{automate put_revision}. Normally used via +Preparation of a workspace-less commit. +See also @command{automate put_revision}. Normally used via @command{automate stdio}. @item Sample output: address@hidden -70a0f283898a18815a83df37c902e5f1492e9aa2 address@hidden +70a0f283898a18815a83df37c902e5f1492e9aa2 @end verbatim @item Output format: @@ -7706,14 +7821,14 @@ @section Automation @item Error conditions: -If the optional base id is unknown prints an error message to stderr and +If the optional base id is unknown prints an error message to stderr and exits with status 1. @end table @item mtn automate put_revision @var{revision-data} address@hidden @strong address@hidden @strong @item Arguments: @var{revision-data} is the new revision. See example below. Note that @@ -7753,8 +7868,8 @@ @section Automation @item Sample output: address@hidden -4c2c1d846fa561601254200918fba1fd71e6795d address@hidden +4c2c1d846fa561601254200918fba1fd71e6795d @end verbatim @item Output format: @@ -7763,7 +7878,7 @@ @section Automation @item Error conditions: -If the changeset is invalid prints an error message to stderr and +If the changeset is invalid prints an error message to stderr and exits with status 1. May abort on invalid formats. If the revision is already present in the database, prints a message to stderr noting this fact, but otherwise works as normal. @@ -7772,7 +7887,7 @@ @section Automation @item mtn automate cert @var{revision} @var{name} @var{value} address@hidden @strong address@hidden @strong @item Arguments: @var{revision} is an existing revision, @var{name} is the certificate name @@ -7789,8 +7904,8 @@ @section Automation @item Sample usage: address@hidden -mtn automate cert 4c2c1d846fa561601254200918fba1fd71e6795d author address@hidden address@hidden +mtn automate cert 4c2c1d846fa561601254200918fba1fd71e6795d author address@hidden @end verbatim @item Output format: @@ -7799,7 +7914,7 @@ @section Automation @item Error conditions: -If the revision is invalid prints an error message to stderr and +If the revision is invalid prints an error message to stderr and exits with status 1. @end table @@ -7886,8 +8001,8 @@ @chapter Hook Reference functions exposing functionality not available with standard Lua. @menu -* Hooks:: All hooks called by monotone. -* Additional Lua Functions:: Extra functionality available to hook writers. +* Hooks:: All hooks called by monotone. +* Additional Lua Functions:: Extra functionality available to hook writers. @end menu @page @@ -7895,7 +8010,7 @@ @section Hooks @section Hooks This section documents the existing hook functions and their default -definitions. +definitions. @subsection Event Notifications and Triggers @@ -7915,7 +8030,7 @@ @subsection Event Notifications and Trig be given by @command{mtn automate get_revision @var{new_id}}. The third parameter, @var{certs}, is a Lua table containing the set of certificate names and values committed along with this version. There is no default -definition for this hook. +definition for this hook. Note that since the @var{certs} table does not contain cryptographic or trust information, and only contains one entry per cert name, it is @@ -7982,7 +8097,7 @@ @subsection Event Notifications and Trig operation. @var{rev_id} is the revision id that the cert is attached to, @var{key} is the key that the cert is signed with, @var{name} is the name of the cert, and @var{value} is the cert value. There is no default -definition for this hook. +definition for this hook. @var{session_id} is used together with @code{note_netsync_start} and @code{note_netsync_end}. If you're not interested in that type of tracking, you can ignore that variable entirely. @@ -7990,7 +8105,7 @@ @subsection Event Notifications and Trig @item note_netsync_pubkey_received (@var{keyname}, @var{session_id}) Called by monotone after a pubkey is received through netsync. @var{keyname} -is the name of the key received. There is no default definition for this hook. +is the name of the key received. There is no default definition for this hook. @var{session_id} is used together with @code{note_netsync_start} and @code{note_netsync_end}. If you're not interested in that type of tracking, you can ignore that variable entirely. @@ -8150,7 +8265,7 @@ @subsection User Defaults Returns @code{true} if you want monotone to remember the passphrase of a private key for the duration of a single command, or @code{false} if you want monotone to prompt you for a passphrase for each certificate -it generates. Since monotone often generates several certificates in +it generates. Since monotone often generates several certificates in quick succession, unless you are very concerned about security you probably want this hook to return @code{true}. @@ -8183,7 +8298,7 @@ @subsection User Defaults Returns @code{true} if @var{filename} should be ignored while adding, dropping, or moving files. Otherwise returns @code{false}. This is most important when performing recursive actions on directories, which -may affect multiple files simultaneously. +may affect multiple files simultaneously. The default definition of this hook recognises a number of common file types and extensions for temporary and generated file types that users @@ -8329,8 +8444,8 @@ @subsection Netsync Transport Hooks local argv = nil - if uri["scheme"] == "ssh" - and uri["host"] + if uri["scheme"] == "ssh" + and uri["host"] and uri["path"] then argv = @{ "ssh" @} @@ -8345,7 +8460,7 @@ @subsection Netsync Transport Hooks table.insert(argv, uri["host"]) end - + if uri["scheme"] == "file" and uri["path"] then argv = @{ @} end @@ -8403,7 +8518,7 @@ @subsection Netsync Transport Hooks @smallexample @group function use_transport_auth(uri) - if uri["scheme"] == "ssh" + if uri["scheme"] == "ssh" or uri["scheme"] == "file" then return false else @@ -8476,8 +8591,8 @@ @subsection Trust Evaluation Hooks end function get_revision_cert_trust(signers, id, name, val) - local trusted_signers = @{ "bob@@happyplace.example.com", - "friend@@trustedplace.example.com", + local trusted_signers = @{ "bob@@happyplace.example.com", + "friend@@trustedplace.example.com", "myself@@home.example.com" @} local t = intersection(signers, trusted_signers) @@ -8588,7 +8703,7 @@ @subsection External Merge Tools Monotone often needs to merge together the work of multiple distributed developers, and uses these hooks to help this process when the merge does not automatically succeed. Often these hooks will be used to invoke -an external interactive merge tool. +an external interactive merge tool. The @ref{Default hooks} include helper functions used by the hooks below to invoke a number of external merge tools known to monotone, and you @@ -8625,10 +8740,10 @@ @subsection External Merge Tools @item get_preferred_merge3_command(@var{tbl}) Returns the results of running an external merge on three strings. address@hidden wraps up the various arguments for each merge command and address@hidden wraps up the various arguments for each merge command and is always provided by @ref{merge3}. If there is a particular editor that you would like to use to perform merge3 operations, override -this hook to specify it. +this hook to specify it. @end ftable @@ -8640,7 +8755,7 @@ @subsection Selector Expansion strings; these hooks are designed to recognise shorthand patterns and expand them to their full form. -For more detail on the use of selectors, see @ref{Selectors}. +For more detail on the use of selectors, see @ref{Selectors}. @ftable @code @item expand_selector (@var{str}) @@ -8682,7 +8797,7 @@ @subsection Attribute Handling This is not a hook function, but a @emph{table} of hook functions. Each entry in the table @code{attr_functions}, at table entry @var{attribute}, is a function taking a file name @var{filename} -and a attribute value @var{value}. The function should ``apply'' the +and a attribute value @var{value}. The function should ``apply'' the attribute to the file, possibly in a platform-specific way. Hook functions from this table are called for each existing attr, @@ -8696,8 +8811,8 @@ @subsection Attribute Handling @smallexample @group -attr_functions["mtn:execute"] = - function(filename, value) +attr_functions["mtn:execute"] = + function(filename, value) if (value == "true") then make_executable(filename) end @@ -8720,27 +8835,27 @@ @subsection Attribute Handling @smallexample @group -attr_init_functions["mtn:execute"] = +attr_init_functions["mtn:execute"] = function(filename) - if (is_executable(filename)) then - return "true" - else - return nil + if (is_executable(filename)) then + return "true" + else + return nil end end -attr_init_functions["mtn:manual_merge"] = +attr_init_functions["mtn:manual_merge"] = function(filename) - if (binary_file(filename)) then + if (binary_file(filename)) then return "true" -- binary files must be merged manually - else + else return nil - end + end end @end group @end smallexample The @code{binary_file} function is also defined as a Lua hook. See address@hidden hooks}. address@hidden hooks}. @end ftable @@ -8753,7 +8868,7 @@ @subsection Validation Hooks @item validate_commit_message (@var{message}, @var{revision_text}, @var{branchname}) This hook is called after the user has entered his/her commit message. address@hidden is the commit message that the user has entered and address@hidden is the commit message that the user has entered and @var{revision_text} is the full text of the changes for this revision, which can be parsed with the parse_basic_io function. The @var{branchname} on which the new revision will be committed if all goes well is passed in as the third @@ -8770,7 +8885,7 @@ @section Additional Lua Functions @section Additional Lua Functions This section documents the additional Lua functions made available to -hook writers. +hook writers. @ftable @code @@ -8778,7 +8893,7 @@ @section Additional Lua Functions This function receives a string containing the name of an external program and returns 0 if it exists on path and is executable, -1 -otherwise. +otherwise. As an example, @code{existonpath("xxdiff")} returns 0 if the program xxdiff is available. On Windows, this function automatically appends ``.exe'' to the @@ -8806,11 +8921,11 @@ @section Additional Lua Functions @end group @end smallexample address@hidden include(@var{scriptfile}) address@hidden include(@var{scriptfile}) This function tries to load and execute the script contained into scriptfile. It returns true for success and false if there is an -error. +error. @item includedir(@var{scriptpath}) @@ -8836,13 +8951,13 @@ @section Additional Lua Functions This function calls the kill() C library function on POSIX systems and TerminateProcess on Win32 (in that case @var{pid} is the process handle). If the optional @var{signal} parameter is missing, SIGTERM -will be used. +will be used. Returns 0 on success, -1 on error. @item make_executable(@var{filespec}) This function marks the named file as executable. On Windows has no -effect. +effect. @item match(@var{glob}, @var{string}) @@ -8851,15 +8966,15 @@ @section Additional Lua Functions @item mkstemp(@var{template}) Like its C library counterpart, mkstemp creates a unique name and -returns a file descriptor for the newly created file. +returns a file descriptor for the newly created file. The value of template should be a pointer to a character buffer loaded with a null-terminated string that consists of contiguous, legal file -ad path name characters followed by six Xs. +ad path name characters followed by six Xs. The function mkstemp replaces the Xs by an alpha-numeric sequence that is chosen to ensure that no file in the chosen directory has that -name. +name. Furthermore, subsequent calls to mkstemp within the same process -each yield different file names. +each yield different file names. Unlike other implementations, monotone mkstemp allows the template string to contain a complete path, not only a filename, allowing users to create temporary files outside the current directory. @@ -8955,10 +9070,10 @@ @chapter Special Topics specifics of how it works. Most users can ignore these sections. @menu -* Internationalization:: Using monotone in non-English locales. -* Hash Integrity:: Notes on probability and failure. -* Rebuilding ancestry:: In case of corruption. -* Mark-Merge:: The merging algorithm used by Monotone. +* Internationalization:: Using monotone in non-English locales. +* Hash Integrity:: Notes on probability and failure. +* Rebuilding ancestry:: In case of corruption. +* Mark-Merge:: The merging algorithm used by Monotone. @end menu @page @@ -9039,7 +9154,7 @@ @heading General Terms international domain names (IDNs) @item punycode -RFC 3492, a "bootstring" encoding of Unicode into ASCII. +RFC 3492, a "bootstring" encoding of Unicode into ASCII. @item IDNA RFC 3490, international domain names for applications, a combination @@ -9051,7 +9166,7 @@ @heading General Terms an IDNA string is this: @smallexample address@hidden address@hidden @address@hidden@{LDH-sanitized(punycode(nameprep(UTF-8-string)))@} @end group @end smallexample @@ -9070,13 +9185,13 @@ @heading General Terms display. @end table - + @heading Filenames @itemize @item -Filenames are subject to normal form conversion. +Filenames are subject to normal form conversion. @item Filenames are subject to an additional normal form stage which adjusts @@ -9124,7 +9239,7 @@ @heading UI messages @heading UI messages -UI messages are displayed via calls to @code{gettext()}. +UI messages are displayed via calls to @code{gettext()}. @heading Host names @@ -9188,7 +9303,7 @@ @heading Packets @item '[' and ']', the packet delimiters. @item -ASCII codes 0x0D (CR), 0x0A (LF), 0x09 (HT), and 0x20 (SP). +ASCII codes 0x0D (CR), 0x0A (LF), 0x09 (HT), and 0x20 (SP). @end itemize @page @@ -9224,9 +9339,9 @@ @heading The analysis is wrong designed to withstand attempts at: @itemize address@hidden address@hidden reversal: deriving an input value from the output address@hidden address@hidden collision: finding two different inputs which hash to the same output @end itemize @@ -9236,7 +9351,7 @@ @heading The analysis is wrong pair of colliding values. This latter probability is sometimes called the hash's ``birthday paradox probability''. address@hidden Accidental collision address@hidden Accidental collision One way of measuring these bounds is by measuring how single-bit changes in the input affect bits in the hash output. The @sc{sha1} @@ -9329,7 +9444,7 @@ @subheading Collision attacks If in the future @sc{sha1} (or, indeed, @sc{rsa}) becomes accepted as broken we will naturally upgrade monotone to a newer hash or public key scheme, and provide migration commands to recalculate existing -databases based on the new algorithm. +databases based on the new algorithm. Similarly, if you do not trust our vigilance in keeping up to date with cryptography literature, you can modify monotone to use any @@ -9407,11 +9522,11 @@ @section Rebuilding ancestry @itemize address@hidden address@hidden When monotone rebuilds ancestry, it generates a new @emph{random} epoch for each branch in the database. address@hidden address@hidden When monotone runs netsync between databases, it checks to make sure that all branches involved in the synchronization have the same epochs. If any epochs differ, the netsync is aborted with no changes @@ -9474,7 +9589,7 @@ @section Mark-Merge @section Mark-Merge Monotone makes use of the Mark-Merge (also known as *-merge) algorithm. -The emails reproduced below document the algorithm. Further information +The emails reproduced below document the algorithm. Further information can be found at @uref{http://revctrl.org/MarkMerge, revctrl.org}. @subheading Initial mark-merge proposal @@ -9546,11 +9661,11 @@ @subheading Initial mark-merge proposal b* a b - iv) \ / + iv) \ / c* c is totally new, so marked a a - \ / + \ / c* a b we're marking places where users expressed @@ -9786,7 +9901,7 @@ @subheading Initial mark-merge proposal \ / c then you figure that the person doing the merge was picking from all -possible resolution values; when you see +possible resolution values; when you see a b \ / b @@ -9844,7 +9959,7 @@ @subheading Initial mark-merge proposal -- Nathaniel --- +-- So let us espouse a less contested notion of truth and falsehood, even if it is philosophically debatable (if we listen to philosophers, we must debate everything, and there would be no end to the discussion). @@ -9925,11 +10040,11 @@ @subheading Improvements to *-merge b* a b - iv) \ / + iv) \ / c* 'c' is totally new, so marked a1 a2 - \ / + \ / c* a b1 we're marking places where users expressed @@ -10166,7 +10281,7 @@ @subheading Improvements to *-merge -- Nathaniel --- +-- "The problem...is that sets have a very limited range of activities -- they can't carry pianos, for example, nor drink beer." @@ -10299,7 +10414,7 @@ @unnumbered General Index @node General Index @unnumbered General Index - + @printindex cp @bye