# # # patch "monotone.texi" # from [118d7d6cd69525944cc0a1ffc7b7e2b122c0be6a] # to [dab7eb70ba607f72f7374fc4e1131585cb676532] # ============================================================ --- monotone.texi 118d7d6cd69525944cc0a1ffc7b7e2b122c0be6a +++ monotone.texi dab7eb70ba607f72f7374fc4e1131585cb676532 @@ -223,7 +223,7 @@ @section Versions of files One way to store multiple versions of a file is, literally, to save a separate @i{complete} copy of the file, every time you make a change. When necessary, monotone will save complete copies of your -files, compressed with the @command{zlib} compression format. +files, compressed with the @code{zlib} compression format. @ifinfo @smallexample @@ -259,7 +259,7 @@ @section Versions of files new version, by applying the delta backwards, and lets your friends change their old version of the file into the new version, by applying the delta forwards. Deltas are usually smaller than full files, so -when possible monotone stores deltas, using a modified @command{xdelta} +when possible monotone stores deltas, using a modified @code{xdelta} format. The details of this format are beyond the scope of this document. @@ -926,7 +926,7 @@ @section Branches which revisions you would like to merge, and which you would like to keep separate. -You can see all the available branches using @code{mtn list branches}. +You can see all the available branches using @command{mtn list branches}. Branches are indicated with certs. The cert name @code{branch} is reserved for use by monotone, for the purpose of identifying the @@ -1157,7 +1157,7 @@ @section Creating a Database @section Creating a Database The first step Jim, Abe and Beth each need to perform is to create a -new database. This is done with the @code{mtn db init} command, +new database. This is done with the @command{mtn db init} command, providing a @option{--db} option to specify the location of the new database. Each programmer creates their own database, which will reside in their home directory and store all the revisions, files and @@ -1275,7 +1275,7 @@ @section Generating Keys to re-enter his passphrase in order to perform security-sensitive tasks. Jim isn't very worried about security (and, more importantly, it simplifies the tutorial text to skip the passphrase prompts) so he -decides to store his passphrase in his @code{monotonerc} file. He does +decides to store his passphrase in his @file{monotonerc} file. He does this by writing a @emph{hook function} which returns the passphrase: @smallexample @@ -1304,9 +1304,9 @@ @section Starting a New Project Before he can begin work on the project, Jim needs to create a @i{workspace} --- a directory whose contents monotone will keep track of. Often, one works on projects that someone else has started, and -creates workspaces with the @code{checkout} command, which you'll +creates workspaces with the @command{checkout} command, which you'll learn about later. Jim is starting a new project, though, so he does -something a little bit different. He uses the @code{mtn setup} +something a little bit different. He uses the @command{mtn setup} command to create a new workspace. This command creates the named directory (if it doesn't already exist), @@ -1314,7 +1314,7 @@ @section Starting a New Project is how monotone recognizes that a directory is a workspace, and monotone stores some bookkeeping files within it. For instance, command line values for the @option{--db}, @option{--branch} or @option{--key} -options to the @code{setup} command will be cached in a file called +options to the @command{setup} command will be cached in a file called @file{_MTN/options}, so you don't have to keep passing them to monotone all the time. @@ -1714,7 +1714,7 @@ @section Synchronising Databases @section Synchronising Databases With Jim's server preparations done, now Abe is ready to fetch Jim's -code. To do this he issues the monotone @code{sync} command: +code. To do this he issues the monotone @command{sync} command: @smallexample @group @@ -2421,7 +2421,7 @@ @section Network Service Revisited will listen on. He should only accept connections at the address used for his website, because some of the provider's other customers might also want to publish their own monotone projects on this host. Jim uses -the @code{--bind=address:port} argument like so: +the @address@hidden:@var{port}} argument like so: @smallexample @group @@ -2437,12 +2437,12 @@ @section Network Service Revisited port number on that address. While he's first testing the setup, Jim uses address@hidden:1234}. This causes the monotone process to listen address@hidden:1234}. This causes the monotone process to listen only to port 1234 on the loopback interface 127.0.0.1, which is not accessible from the network, so Jim doesn't expose an open port to the rest of the world until he's satisfied with the permissions configuration. You can cause monotone to listen on all interfaces on -port 1234 by leaving out the address part like @code{--bind=:1234}. +port 1234 by leaving out the address part like @option{--bind=:1234}. When he's satisfied the server is set up correctly, Jim does an initial @command{sync} with the new database, filling it with all the revision @@ -2898,7 +2898,7 @@ @section Scripting computers, and serving neither audience well, we elected to create a separate interface to make programmatically extracting information from monotone easier. The command line interface has a command address@hidden; this command has subcommands that print various sorts address@hidden; this command has subcommands that print various sorts of information on standard output, in simple, consistent, and easily parseable form. @@ -2961,7 +2961,7 @@ @section Quality Assurance Many of monotone's operations involve searching the revision graph for the ancestors or descendents of a particular revision, or extracting the ``heads'' of a subgraph, which is the subgraph's set of nodes with -no descendents. For example, when you run the @code{update} command, +no descendents. For example, when you run the @command{update} command, monotone searches the subgraph consisting of descendents of the base revision of the current workspace, trying to locate a unique head to update the base revision to. @@ -3179,41 +3179,41 @@ @section Reserved Certs @item author This cert's value is the name of a person who committed the revision the cert is attached to. The cert is generated when you commit a -revision. It is displayed by the @code{log} command. +revision. It is displayed by the @command{log} command. @item branch This cert's value is the name of a branch. A @code{branch} cert associates a revision with a branch. The revision is said to be ``in the branch'' named by the cert. The cert is generated when you commit -a revision, either directly with the @code{commit} command or -indirectly with the @code{merge} or @code{propagate} commands. The +a revision, either directly with the @command{commit} command or +indirectly with the @command{merge} or @command{propagate} commands. The @code{branch} certs are read and directly interpreted by @emph{many} monotone commands, and play a fundamental role in organizing work in any monotone database. @item changelog This cert's value is the change log message you provide when you -commit a revision. It is displayed by the @code{log} command. +commit a revision. It is displayed by the @command{log} command. @item comment This cert's value is an additional comment, usually provided after committing, about a revision. Certs with the name @code{comment} can -be applied to files as well, and will be shown by the @code{log} +be applied to files as well, and will be shown by the @command{log} command. @item date This cert's value is an ISO date string indicating the time at which a -revision was committed. It is displayed by the @code{log} command, and +revision was committed. It is displayed by the @command{log} command, and may be used as an additional heuristic or selection criterion in other commands in the future. @item tag This cert's value is a symbolic name given to a revision, which may be -used in the future as a way of selecting versions for @code{checkout}. +used in the future as a way of selecting versions for @command{checkout}. @item testresult This cert's value is interpreted as a boolean string, either @code{0} -or @code{1}. It is generated by the @code{testresult} command and +or @code{1}. It is generated by the @command{testresult} command and represents the results of running a particular test on the underlying revision. Typically you will make a separate signing key for each test you intend to run on revisions. This cert influences the @@ -3267,7 +3267,7 @@ @section File Attributes The attribute mechanism was originally motivated by the fact that some people like to store executable programs in version control systems, and would like the programs to remain executable when they check out a -workspace. For example, the @code{configure} shell script commonly +workspace. For example, the @command{configure} shell script commonly shipped with many programs should be executable. Similarly, some people would like to store devices, symbolic links, read-only files, and all manner of extra attributes of a file, not directly related to @@ -3283,7 +3283,7 @@ @section File Attributes Windows users can view and modify the attr like anyone else.) Attrs in the current workspace can be seen and modified using the address@hidden attr} command; see @ref{Workspace}. Attrs can also be found address@hidden attr} command; see @ref{Workspace}. Attrs can also be found by examining any manifest directly. You can tell monotone to automatically take actions based on these @@ -3869,7 +3869,7 @@ @heading Removing Directories and Files Monotone does not require that you erase a file from the workspace before you drop it. Dropping a file merely removes its entry in the -manifest of the current revision unless you give it the @command{--execute} +manifest of the current revision unless you give it the @option{--execute} flag, which tells monotone to go ahead and also remove it from the filesystem. @@ -4031,11 +4031,11 @@ @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, @code{disapprove}s contract is that disapprove(A) gives a +Conceptually, @command{disapprove}s contract is that disapprove(A) gives a revision B such that whenever B is merged with a descendent 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 @code{disapprove} command +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 descendent in the multi-ancestor case. @@ -4082,7 +4082,7 @@ @section Tree @item mtn explicit_merge @var{id} @var{id} @var{destbranch} This command merges exactly the two @var{id}s you give it, and places the result in branch @var{destbranch}. It is useful when you need more -control over the merging process than @code{propagate} or @code{merge} +control over the merging process than @command{propagate} or @command{merge} give you. For instance, if you have a branch with three heads, and you only want to merge two of them, you can use this command. Or if you have a branch with two heads, and you want to propagate one of them to @@ -4342,11 +4342,12 @@ @section Workspace @item mtn pluck address@hidden @itemx mtn pluck address@hidden address@hidden -This command takes changes made at any point in history, and attempts -to edit your current workspace to include those changes. The end -result is identical to running @code{mtn diff -r FROM -r TO | patch --p0}, except that this command uses monotone's merger, and thus -intelligently handles renames, conflicts, and so on. +This command takes changes made at any point in history, and attempts to +edit your current workspace to include those changes. The end result is +identical to running @command{mtn diff @option{-r} @var{from} address@hidden @var{to} | patch @option{-p0}}, except that this command +uses monotone's merger, and thus intelligently handles renames, +conflicts, and so on. If only one revision is given, applies the changes made in @var{to} as compared with @var{to}'s parent. If two revisions are given, applies @@ -4561,26 +4562,26 @@ @section Informative history summaries. Each summary contains author, date, changelog and comment information associated with a revision. -If @code{--brief} is given, the output consists of one line per revision +If @option{--brief} is given, the output consists of one line per revision with the revision ID, the author, the date and the branches (separated with commas). -If @address@hidden is given, at most @var{n} log entries will be +If @address@hidden is given, at most @var{n} log entries will be given. -If @address@hidden is given, at most @var{n} log entries towards +If @address@hidden is given, at most @var{n} log entries towards the current head revision will be given from the workspace's base revision in forward-ancestry order. This is useful to review changes that will be applied to the workspace when @command{update} is run. By default, the log entries for merge nodes are shown. If address@hidden is given, the log entries for these nodes will be address@hidden is given, the log entries for these nodes will be excluded. -If @code{--no-files} is given, the log output excludes the list of +If @option{--no-files} is given, the log output excludes the list of files changed in each revision. -Specifying @code{--diffs} causes the log output to include a unified +Specifying @option{--diffs} causes the log output to include a unified diff of the changes in each revision. If one or more revision IDs are given, the command starts tracing back @@ -4594,11 +4595,11 @@ @section Informative @itemx mtn annotate address@hidden [--brief] @var{file} Dumps an annotated copy of the file to stdout. In the absence of the address@hidden flag, each line of the file address@hidden 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 @code{--brief} is specified, the output is in the form +If @option{--brief} is specified, the output is in the form .. by : Only the first 8 characters of the revision id are displayed, the author cert value is truncated at the first @code{@@} or space @@ -4627,8 +4628,8 @@ @section Informative @code{fa36}. This command is intended to be used by programmable completion systems, such as those in @command{bash} and @command{zsh}. -The complete command for keys and revisions have a @code{--verbose} option. -Programmable completion systems can use @code{--verbose} output to +The complete command for keys and revisions have a @option{--verbose} option. +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: @@ -4681,9 +4682,9 @@ @section Informative @option{--unified}, @option{--context}, @option{--show-encloser}, and @option{--external}. By default, monotone uses its built-in diff algorithm to produce a listing in ``unified diff'' format (analogous -to running the program @code{diff -u}); you can also explicitly +to running the program @command{diff @option{-u}}); you can also explicitly request this with @option{--unified}. The built-in diff algorithm can -also produce ``context diff'' format (analogous to @code{diff -c}), +also produce ``context diff'' format (analogous to @command{diff @option{-c}}), which you request by specifying @option{--context}. The short options that @command{diff} accepts for these modes, @option{-u} and @option{-c}, also work. @@ -4702,7 +4703,7 @@ @section Informative @option{--unified} requests the ``unified diff'' format, the default. @option{--context} requests the ``context diff'' format (analogous to -running the program @code{diff -c}). Both of these formats are +running the program @command{diff @option{-c}}). Both of these formats are generated directly by monotone, using its built-in diff algorithm. Sometimes, you may want more flexibility in output formats; for these @@ -4710,7 +4711,7 @@ @section Informative an external program to generate the actual output. By default, the external program is @code{diff}, and you can use the option @option{--diff-args} to pass additional arguments controlling -formatting. The actual invocation of @code{diff}, default arguments +formatting. The actual invocation of @command{diff}, default arguments passed to it, and so on, are controlled by the hook @code{external_diff}; see @ref{Hooks} for more details. @@ -4956,7 +4957,7 @@ @section Certificate @ftable @command @item mtn approve @var{id} -This command is a synonym for @code{mtn cert @var{id} branch +This command is a synonym for @command{mtn cert @var{id} branch @var{branchname}} where @var{branchname} is the current branch name (either deduced from the workspace or from the @option{--branch} option). @@ -4965,21 +4966,21 @@ @section Certificate @item mtn comment @var{id} @itemx mtn comment @var{id} @var{comment} -These commands are synonyms for @code{mtn cert @var{id} +These commands are synonyms for @command{mtn cert @var{id} comment @var{comment}}. If @var{comment} is not provided, it is read from @code{stdin}. @item mtn tag @var{id} @var{tagname} -This command is a synonym for @code{mtn cert @var{id} tag +This command is a synonym for @command{mtn cert @var{id} tag @var{tagname}}. @item mtn testresult @var{id} 0 @itemx mtn testresult @var{id} 1 -These commands are synonyms for @code{mtn cert @var{id} -testresult 0} or @code{mtn cert @var{id} testresult 1}. +These commands are synonyms for @command{mtn cert @var{id} +testresult 0} or @command{mtn cert @var{id} testresult 1}. @end ftable @@ -5320,9 +5321,9 @@ @section Automation @node Automation @section Automation -This section contains subcommands of the @code{mtn automate} -command, used for scripting monotone. All give output on stdout; they -may also give useful chatter on stderr, including warnings and error +This section contains subcommands of the @command{mtn automate} command, +used for scripting monotone. All give output on @code{stdout}; they may +also give useful chatter on @code{stderr}, including warnings and error messages. @@ -5341,7 +5342,7 @@ @section Automation @item Purpose: Prints version of the automation interface. Major number increments -whenever a backwards incompatible change is made to the @code{automate} +whenever a backwards incompatible change is made to the @command{automate} command; minor number increments whenever any change is made (but is reset when major number increments). @@ -7694,7 +7695,7 @@ @subsection Trust Evaluation Hooks @code{branch} certificate, in which case it must be signed by @emph{two} or more trusted keys. This is one way of requiring that the revision has been approved by an extra ``reviewer'' who used the address@hidden command. address@hidden command. @item accept_testresult_change (@var{old_results}, @var{new_results}) @@ -7769,7 +7770,7 @@ @subsection External Diff Tools will be passed in as @var{diff_args}. Otherwise @var{diff_args} will be nil. -The default implementation of this hook calls the program @code{diff}, +The default implementation of this hook calls the program @command{diff}, and if @option{--diff-args} were not passed, takes default arguments from the lua variable @code{external_diff_default_args}. You can override this variable in your configuration file, without overriding @@ -8379,7 +8380,7 @@ @heading File contents @item File SHA1 values are calculated from the internal form of the conversions. If the external form of a file differs from the internal -form, running a 3rd party program such as @code{sha1sum} will produce +form, running a 3rd party program such as @command{sha1sum} will produce different results than those entries shown in a corresponding manifest. @end itemize @@ -8638,7 +8639,7 @@ @section Rebuilding ancestry If either of these events occur, we will provide migration commands and explain how to use them for the situation in question; this much is necessarily somewhat unpredictable. In the past we've used the address@hidden rebuild} command, which extracts the ancestry graph from the address@hidden rebuild} command, which extracts the ancestry graph from the database and then recreates revisions from the manifests only --- this preserves the contents of each snapshot, but breaks tracking of file identity across renames --- and then reissues all existing certs that @@ -8648,7 +8649,7 @@ @section Rebuilding ancestry unavoidable --- if you could sign with other people's keys, that would be a rather serious security problem!} -While the @code{db rebuild} command can reconstruct the ancestry graph +While the @command{db rebuild} command can reconstruct the ancestry graph in @emph{your} database, there are practical problems which arise when working in a distributed work group. For example, suppose our group consists of the fictional developers Jim and Beth, and they need to @@ -8721,7 +8722,7 @@ @heading Best practices ancestries cross organizational boundaries, matters are more complex. The basic approach is to do a local rebuild, then after carefully examining the new revision IDs to convince yourself that the rebuilt -graph is the same as the upstream subgraph, use the special @code{db +graph is the same as the upstream subgraph, use the special @command{db epoch} commands to force your local epochs to match the upstream ones. (You may also want to do some fiddling with certs, to avoid getting duplicate copies of all of them; if this situation ever arises in real