elisp-vcs/dvc/texinfo/dvc-intro.texinfo

\input texinfo

@c Author : Stephen Leake <stephen_leake@stephe-leake.org>
@c Web    : http://www.stephe-leake.org/

@setfilename dvc-intro.info
@settitle DVC: Introduction to the GNU Emacs interface to
distributed version control systems.

@setchapternewpage off

@node Top
@top DVC Intro

@smallexample
@group
  Copyright (C) 2007 - 2011 Stephen Leake
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.2
  or any later version published by the Free Software Foundation;
  with no Invariant Sections, with no Front-Cover Texts, and with no
  Back-Cover Texts. A copy of the license is included in the section
  entitled ``GNU Free Documentation License''.
@end group
@end smallexample

@menu
* Overview::
* Installing::
* Invoking::
* Status Display::
* Key bindings::
* Previewing updates::
* Merging::
* mtn command line::
* Common Errors and Solutions::
* GNU Free Documentation License::

@detailmenu
 --- The Detailed Node Listing ---

Overview

* Basic DVC::
* Compare to CVS::

Invoking

* xmtn-status-one::
* xmtn-propagate-one::
<<<<<<< TREE
=======
* xmtn-sync-review::
>>>>>>> MERGE-SOURCE

Key bindings

* status buffer keys::
* Ediff keys::
* Log edit keys::
* DVC log keys::
* DVC diff keys::
* mtn conflicts keys::

Common Errors and Solutions

* Attach blocked by unversioned path::
* Revision id does not match conflict file::

@end detailmenu
@end menu

@node Overview
@chapter Overview

DVC is a common interface to several extremely powerful and flexible
version control systems, such as Gnu arch, monotone, bzr, and others
(known as 'backends' to DVC).

DVC provides the same (or at least similar) user interface for each
backend, making it easier to use multiple backends in related
projects. It also automates some tasks, and provides guidance to the
user as to what needs to be done.

DVC is not included with the standard Gnu emacs distribution. It is
provided in source form via a bzr repository (see @ref{Installing}).

If you are not already familiar with version control systems, please
read @ref{Basic DVC}.

One of the most important features of the DVC user interface is that
it identifies what files in a project need attention of some sort; you
have changed them in your working directory, or someone else has
changed them in the repository, or they've been deleted or are new,
etc. DVC presents a list of all such files, and makes it easy to see
what needs to be done for each file.

When committing files, ediff is used to allow reviewing the changes,
so an appropriate change comment can be written.

DVC replaces the command-line interface to the backends for the most
common operations, but it is still necessary to use the command line
at times. Creating a repository, starting a project in a repository,
and managing branches require command line operations.

This manual describes the DVC user interface, and gives examples of
some required command line operations, using the monotone backend.

It also describes some DVC extensions that are specific to the
monotone backend.

@menu
* Basic DVC::
* Compare to CVS::
@end menu

@node Basic DVC
@section Basic DVC

Here we give a brief introduction to general concepts of distributed
version control systems, focusing on the concepts that are needed to
use DVC, and providing common terminology.

Each backend will have its own documentation, and terminology that
differs from this. The terms here are taken mostly from the monotone
backend.

Let's start with some definitions:

@table @dfn
@item workspace
Each user has a workspace, containing a copy of the files she is
working on. This is typically a directory tree. In the root directory
of the tree there is typically a directory containing backend control
files, used only by the backend.

@item database
The database stores copies of all files in the workspace (and typically
more than one workspace), together with all of the change history and
other meta-information. The database is never edited directly; only
the backends modify it.

@item local database
A database on the user's machine. This database is used to
control all workspaces on the user's machine.

@item remote database
A database on a remote machine. This may be another user's local
database, or a central database set up specifically for sharing files.
The user interacts with the remote database in order to retrieve other
user's files, or deliver files to them.

@item revision
The state of the entire workspace, usually including the set of
changes to the workspace that transform it from the previous
revision. Most operations on the database involve revisions, and all
changes to files are part of a revision.

@item branch
A label for distinct trees of revisions. There are two main uses for
branches; parallel development on a single project, and completely
separate projects. Branches of a single project are typically merged
back together (this is called ``propagating''), while completely
separate projects are not.

A database can store any number of branches.

@item heads
The revisions that are the leaves of the history tree on a single
branch. In monotone, there can be any number of heads on a branch (see
@ref{Merging}).

@item merge
The process of combining multiple heads of a branch into one
head. This can encounter conflicts that require user resolution; see
@ref{Merging}.

@item propagate
One branch can be ``propagated'' to another. This is a form of
merging; it merges all the changes from one branch into another,
starting from their common ancestor (which is usually the previous
propagate between the two branches).

This is how changes in a development branch are promoted to the main
branch.

Since propagating is a form of merging, it can encounter all of the
same conflicts that merging can.

@item *dvc-status* buffer
A main user interface buffer. It shows all files in the workspace that
need attention. Single keystrokes invoke various operations.
@xref{Status Display}, for more details.

The name of the buffer is not literally @dfn{*dvc-status*}; instead,
@dfn{dvc} is replaced by the backend name; @dfn{xmtn} for monotone,
@dfn{bzr} for bzr, etc. But in this document, we will use the name
@dfn{*dvc-status*}.

@item *dvc-diff* buffer
Another main user interface buffer. It shows the files changed in a
particular revision, together with the diffs of the changes. Single
keystrokes invoke various operations.

@end table

Users edit files in their workspace, then use DVC to synchronize the
workspace with the local database. Later, they use the command line to
synchronize their local database with a remote database. This allows
each user to make changes locally but still under change control,
without affecting other users until they each choose to synchronize.

@node Compare to CVS
@section Compare to CVS
Since many people are familiar with the CVS version control system, we
compare that with DVC, and monotone in particular.

In CVS, each file is committed separately; in DVC, all files in a
workspace are committed together. This makes sure that all changes
that are related are committed together.

This means the commit log message mentions all files that have
changes; it is a much longer message, but there are fewer of them, and
the message can more easily describe changes that affect more than one
file.

In CVS, you must always have access to the remote server. In DVC, you
work with a local database, then separately sync that database with a
remote server. Thus DVC is useful when not on a network; monotone can
even sync via USB disk rather than a network connection.

This means there are two steps to syncing a workspace with the central
server, which can be annoying. On the other hand, the sync process
syncs all projects in the database at once; with monotone, it lets you
know what projects have changes.

Otherwise the primary Emacs interface to CVS and DVC are very similar,
although DVC has many secondary interfaces that CVS does not have.

@node Installing
@chapter Installing
Install bzr; see @url{http://bazaar.canonical.com/en/}.

Retrieve the DCV source; see
@url{https://gna.org/projects/dvc#options} for general information.

In a bash shell:
@example
cd ~
bzr get http://bzr.xsteve.at/dvc/
cd ~/dvc
autoconf
./configure
make
@end example

In your @file{.emacs}, add @code{(load-file (expand-file-name "~/dvc/dvc-load.el"))}

@node Invoking
@chapter Invoking

Before invoking DVC, you may want to ensure that the local database is
synchronized with the central database, via a backend-specific
command line.

You typically invoke DVC with the Emacs command @command{dvc-status}
or @command{dvc-diff}. This prompts for a workspace; it should be the
top level directory in your working directory tree.

You can also create shortcuts in text files to invoke dvc:

@example
(dvc-status (expand-file-name "~/dvc"))
(dvc-diff nil (expand-file-name "~/dvc"))
@end example

These can be executed with @key{C-x C-e}, and are a handy way of
keeping track of several workspaces.

@command{dvc-status} or @command{dvc-diff} run the corresponding
backend command, comparing the workspace against the local database,
and presenting the information in the @dfn{*dvc-status*} or
@dfn{*dvc-diff*} buffer.

For monotone, there are higher-level starting points:
@table @command
@item xmtn-status-one
Summarizes the status of one workspace.

@item xmtn-status-multiple
Similar to @command{xmtn-status-one}, but shows all workspaces
immediately under a root directory.

@item xmtn-propagate-one
Supervises propagating one workspace.

@item xmtn-propagate-multiple
Supervises propagating several workspaces.

<<<<<<< TREE
=======
@item xmtn-sync-sync
Syncs the local database with a remote database, then runs
xmtn-sync-review.

@item xmtn-sync-review
Reviews saved output of a command-line @command{mtn automate sync},
displays branches that have been transferred. This is useful for syncs
<<<<<<< TREE
that take a long time, because external commands display the tickers
much better than DVC does.

The external sync should redirect stdout to @file{~/.dvc/sync.basic_io}.

>>>>>>> MERGE-SOURCE
=======
that take a long time, because the command-line displays progress
tickers.
>>>>>>> MERGE-SOURCE
@end table

@menu
* xmtn-status-one::
* xmtn-propagate-one::
<<<<<<< TREE
=======
* xmtn-sync-review::
>>>>>>> MERGE-SOURCE
@end menu

@node xmtn-status-one
@section xmtn-status-one
Summarizes the status of one workspace, in a @dfn{xmtn-multi-status}
buffer. The branch name is shown, followed by possible appropriate
actions. As each action is performed, it is replaced by the next
action, until there are none left.

Similarly, @command{xmtn-status-multiple} shows the status of all
workspaces immediately under a root directory.

Actions are invoked with @key{M-d}.

The possible actions are:
@table @dfn
@item need-refresh
Shown while the backend is computing, or the user is performing
operations in an associated @dfn{*xmtn-multi-status*} buffer.

@item commit
Open an @dfn{*xmtn-status*} buffer to commit changes.

@item resolve conflicts
Open an @dfn{*xmtn-conflicts*} buffer to resolve conflicts; see @ref{Merging}.

@item show heads
Open an @dfn{*xmtn-revlist*} buffer to show the current head revisions.

@item merge
Perform the merge, using the conflict resolutions.

@item update
Update the workspace to the current head revision (must be merged).

@item update preview
Open an @dfn{*xmtn-revlist*} buffer to review the revisions that will
be included in the next update.

@item update review
Open an @dfn{*xmtn-revlist*} buffer to review the revisions that were
included in the most recent update.

@item ignore local changes
Don't show @dfn{commit}.

@item refresh
Recompute the @dfn{*xmtn-multi-status*} display.

@item clean/delete
Delete conflicts and conflict resolution files, and delete
the workspace from the display.

@end table

@node xmtn-propagate-one
@section xmtn-propagate-one
@command{xmtn-propagate-one} supervises the process of propagating
from one workspace to another, in an @dfn{xmtn-propagate} buffer.

The display shows one source and destination branch pair, and possible
appropriate actions. As each action is performed, it is replaced by
the next action, until there are none left.

Similarly, @command{xmtn-propagate-multiple} supervises the
propagation of all workspaces immediately under two root
directories. This is useful when several related projects branch
together.

In the list of actions, ``from'' stands for the name of the source
branch, ``to'' the name of the destination branch.

Actions are invoked with @key{M-d}.

The possible actions are:
@table @command
@item status ``from''
@itemx status ``to''
Start an @dfn{xmtn-multi-status} buffer for the specified workspace,
to allow commit, update preview, or merge with
conflict resolution.

@itemx update ``to''
Update the specified workspace to the current head revision (must be
merged). This bypasses the @dfn{xmtn-multi-status} buffer, and
therefore does not provide for update preview. It does allow for
update review.

@item ignore local changes ``from''
@item ignore local changes ``to''
Don't show @dfn{need commit}; assume the workspace is
committed. Useful when you know that any local changes won't interfere
with the propagate.

@item resolve conflicts
Open an @dfn{*xmtn-conflicts*} buffer in the destination workspace to
resolve propagate conflicts; see @ref{Merging}.

@item propagate
Propagate the branch pair, using the conflict resolutions.

@item refresh
Recompute the display. If prefixed with @key{C-u}, force examining
workspaces for local changes.

@item clean/delete
Delete conflicts and conflict resolution files, and delete
the workspace from the display.

@end table

<<<<<<< TREE
=======
@node xmtn-sync-review
@section xmtn-sync-review
@command{xmtn-sync-review} supervises the process of updating local
workspaces after a command line operation that synchronizes the local
and remote databases.

The command line operation should redirect stdout to
@file{~/.dvc/sync.basic_io}. Most users will want to define shell
functions to invoke common syncs. For example:

@example
    mtn --db ~/monotone-dbs/gds.db automate sync --ticker=count "ssh:user@@host/gds.db?*" >> ~/.dvc/sync.basic_io
@end example

The @command{xmtn-sync-review} display shows each branch that was
transferred, with a count of how many revisions were sent and
received.

The user may set the variable @code{xmtn-sync-sort} to a function that
indicates how to order the branches in the display.

Actions on branches are invoked with @key{M-d}.

The possible branch actions are:
@table @command
@item status
Start an @dfn{xmtn-multi-status} buffer for the workspace assoicated
with the specified branch, to allow commit, update preview, update
followed by update review, or merge with conflict resolution.

The user may set the variable @code{xmtn-sync-guess-workspace} to a
function that returns a workspace given a branch. Otherwise, the user
is prompted for the workspace location; the location is cached for
future use.

@item update
Start an @dfn{xmtn-multi-status} buffer for the workspace assoicated
with the specified branch, then perform @command{update} (if
appropriate). This is often convenient when you know the workspace has
no local changes.

@itemx brief
Show the first line of the changelog for each revision received.

@itemx full
Show the complete changelog for each revision received.

@item clean
Delete the branch from the display.

Branches that are not cleaned are cached; they will reappear the next
time @code{xmtn-sync-review} is run.

@end table

In addition, there are global actions:
@table @command
@item next
Move to the next branch

@item prev
Move to the previous branch

@item save-quit
Save the displayed branches, quit.

@item save
Save the displayed branches.

@end table

>>>>>>> MERGE-SOURCE
@node Status Display
@chapter Status Display

After invoking @command{dvc-status}, you are presented with the
@dfn{*dvc-status*} buffer.

The detailed format differs depending on the backend. This
presentation is close to the bzr and mtn formats.

The buffer contains a header, such as:

@example
Status for c:/Projects/GDS/common/main/:
  base revision : e946839c833b15e6bf12bd1536764e1106c41924
  branch        : common.main
  branch is merged
  base revision is a head revision
@end example

The last two lines are important; either may have ``not'' in it.

If the branch is not merged, it must be merged before an update can be
done; see @ref{Merging}. However, commits can be done when the branch
is not merged; this allows saving work before attempting the merge.

If the base revision is not a head revision, there are updates that
need to be applied to the workspace. The updates may be reviewed first
using @key{M m}; they may be applied using @key{M u}.

In the main body of the buffer, there is one line for each file in the
workspace that needs attention. For example:

@example
 * modified      hardware/gds-hardware-pmrd_wrapper.adb
   unknown       build/ip1k110_quartus/serv_req_info.txt
 E modified      hardware/test/test_hardware-one_harness.adb
@end example

Each line has three fields:

@table @dfn
@item Mark
Either blank (not marked), '*' (marked), or 'E' (excluded). Most
commands can apply to a group of marked files, but some cannot (they
warn if a group is marked).

Excluded files are under configuration management, but are excluded
from commits. This is used for files that each user modifies, such as
development test drivers.

@item Status
A phrase indicating the status of the file; see the table below.

@item File name
Gives the file name of the working file, with a path relative to the
root directory.

@end table

In addition, some files will have extra status information that
appears on the next line, indented.

The following table defines each status phrase, and gives the set of
actions that can be taken for each. The action shown is from the DVC
menu; the equivalent key is also given.

Other actions (such as commit) apply to all files; they are discussed
later.

@table @samp
@c the list of status phrases is in
@c /Gnu/dvc/lisp/dvc-fileinfo.el dvc-fileinfo-status-image
@c keep this list in the same order
@item Added
    Working file has been added, but not committed.
    @table @samp
    @item @key{r} Delete
        Remove the file from the workspace, do not commit it.
Do this if you've changed your mind.
    @end table

@item Conflict
A conflict was detected while merging.
The same lines have been edited differently by different people.

This status does not appear with the monotone back-end.

@table @samp
@item @key{<enter>} Edit the file.
Either resolve the conflict
manually, or use @code{M-x smerge-ediff}. Execute @code{M-x
dvc-resolve} when finished to inform the back-end that the
conflict is resolved.
@item @key{U} Revert
Delete the working copy, replace it with the database copy. Do
this if you decide the changes are not correct.
@end table

@item Deleted
    Working file has been marked for deletion, but not committed.
    @table @samp
    @item @key{a} Add
        Undo the removal.
    @end table

@item Ignored
    Working file is ignored by the back-end. Files with this status
are not typically shown - ignored files are ignored by DVC as well.
They can be enabled by setting @code{dvc-status-display-ignored} to
nil.
    @table @samp
    @item @key{# e}
Edit the back-end ignore file.
    @end table

@item Known
    Working file is known to the back-end, and unchanged. Files with
this status are not typically shown. They can be enabled by setting
@code{dvc-status-display-known} to nil. There are no appropriate
actions.

@item Missing
    A previously known file has been deleted from the workspace, but
    not marked for deletion.
    @table @samp
    @key{U} Revert
Restore the file to the workspace from the database.
    @item @key{r} Delete
Mark the file for deletion.
    @end table

@item Modified
    A changed file in the workspace.
    @table @samp
    @item @key{e} ediff
Review differences and collect a change comment.
    @item @key{U} Revert
Delete the working copy, replace it with the database copy. Do
this if you decide your changes are not correct.
    @end table

@item Rename-source
    Working file has been marked as renamed but not committed. No
    appropriate actions.

@item Rename-target
    Working file has been marked as renamed but not committed. No
    appropriate actions.

@item Unknown
    Working file is unknown.
    @table @samp
    @item @key{a} Add
    The file is a new source file; add it to the current revision. This will
change the status to 'Added'.
    @item @key{i} Ignore
    The file is an output file of some sort (ie object file, test output).
Ignore it in all future DVC sessions.
    @item @key{I} Ignore extension in dir
    Ignore all files with this extension in this directory.
    @item @key{M-I} Ignore extension
    Ignore all files with this extension in all directories.
    @item @key{r} Delete
    The file is a scratch file, or was created by mistake. Remove it from
the workspace.
    @end table
@end table

Changes are committed all at once; the set of changes to the entire
workspace is called a ``revision''. @key{c} opens the
@code{*dvc-log-edit*} buffer, where you can write a change comment.
Then @key{C-c C-c} commits all changes.

The key @key{M-d} invokes a function called ``Do the Right Thing''. If
there is only a single choice (or an extremely common choice) in the
table above, it does that action. Otherwise, it presents a short list
of the actions, in the message buffer, reminding the user of the
appropriate options. Note that @key{M-d} means meta-d (alt-d on most
PC keyboards))

@node Key bindings
@chapter Key bindings

Here is a summary of the most useful key bindings in the various
buffers associated with DVC.

@menu
* status buffer keys::
* Ediff keys::
* Log edit keys::
* DVC log keys::
* DVC diff keys::
* mtn conflicts keys::
@end menu

@node status buffer keys
@section status buffer keys
In a @code{*dvc-status*} buffer:

@table @key
@item M-d
Do the right thing for the current file.

@item c
Open a @code{*dvc-log-edit*} buffer to accumulate comments for a
commit.

@item M m
Show missing revisions; changes that will be applied by update.

@item M M
Merge current heads; see @ref{Merging}.

@item M u
Update to the current head.

@item R
Rename a missing to an unknown file. The two files must be marked
first, and they must be the only files marked.

@item t
Create an entry in the @code{*dvc-log-edit*} for the current diff.

@end table

@node Ediff keys
@section Ediff keys
In an Ediff control buffer (the small window with Ediff in the title bar):

@table @key
@item a
Copy from buffer A to buffer B.

@item b
Copy from buffer B to buffer A.

@item n
Move to next diff.

@item p
Move to previous diff.

@item q
Quit Ediff.

@item t
Create an entry in the @code{*dvc-log-edit*} for the current diff.

@item $$
Focus on conflicts in a merge.

@item ?
Show the help summary for Ediff. @key{?} hides it again.

@end table

@node Log edit keys
@section log edit keys
In the @code{*dvc-log-edit*} buffer:

@table @key
@item C-c C-c
Commit. Note that this is the only way to actually commit.

@end table

@node DVC log keys
@section DVC log keys
In a @code{*xmtn-log*} buffer:

@table @key
@item n
move to the next revision

@item p
move to the previous revision

@item =
show a diff of the changes in a single revision

@item C-=
show a diff between the revision and the workspace

@end table

@node DVC diff keys
@section DVC diff keys
In a @code{*dvc-diff*} buffer:

@table @key
@item e
show ediff for current file

@item j
jump between file list and diff hunks

@item n
move to the next diff hunk

@item p
move to the previous diff hunk

@end table

@node mtn conflicts keys
@section mtn conflicts keys
In a @code{*xmtn-conflicts*} buffer:

@table @key
@item C
Delete conflicts file and any resolution files.

@item c
Clear the current resolution, so you can specify a different one.

@item n
Move to the next conflict.

@item N
Move to the next unresolved conflict.

@item p
Move to the previous conflict.

@item P
Move to the previous unresolved conflict.

@item q
Quit the @code{*xmtn-conflicts*} buffer. The conflicts file and
associated resolution files are saved.

@item r
Specify a resolution for the current conflict. This prompts with a
choice of resolutions appropriate for the current conflict; select the
appropriate resolution by number. See @ref{Merging}, for information
on the possible resolutions.

@item M-d
Same as @key{r}

@end table

@node Previewing updates
@chapter Previewing updates
To preview updates before applying them to your workspace, use the
@code{dvc-missing} command; it's on the status buffer menu at
@code{DVC | Merge/Update | show missing}.

@code{dvc-missing} can also be invoked via the Emacs command line
(@key{M-x}); that prompts for a local tree.

Invoking @code{dvc-missing} brings up an @code{*dvc-log*} window,
showing revisions that are in your local database but not yet applied
to the workspace.

The revisions are listed oldest first.

You can view the changes made in a single revision, or from that
revision to the current workspace.

See @xref{Log edit keys}, for key bindings.

@key{=} and @key{C-=} bring up a @code{*dvc-diff*} buffer for the
revision selected. The diffs are shown in Gnu diff format; all files
in one @code{*dvc-diff*} buffer. There is a list of the files at the
top of the buffer. See @xref{DVC diff keys}, for key bindings.

Note that you can also review updates after they have been
applied. This is often more useful, because you can edit the workspace
file to fix problems caused by the update, or just to see the final
state after all revisions have been applied.

@node Merging
@chapter Merging
Monotone allows multiple people to each commit to their local
database. Then when the databases are synced, there are multiple heads
for the branch; one head for each developer that commited since the
last sync.

These multiple heads must be merged before a local workspace can be
updated to the head of the branch; there must be only one head to
update to. The monotone command line allows updating to one head of an
unmerged branch, but DVC does not support this.

When the changes in the different heads are to different files, or to
different parts of the same file, monotone can perform the merge
itself. However, when there are changes to the same parts of one file,
it needs help; this is called a content conflict.

An @code{*xmtn-conflicts*} buffer shows all conflicts in a merge or
propagate. You can work thru the list one a time, using @key{M-d}
to specify conflict resolutions. The list is saved in a file, so you
can come back to it later.

The conflicts that monotone knows how to resolve internally have
resolutions of @code{resolved-internal}; the others have no
resolutions.

The conflicts file and associated resolution files are stored in the
monotone bookkeeping area. They must be deleted when you are done with
them; use @key{C C} for that.

@key{M-d} prompts with a list of appropriate resolutions for the
current conflict; select the appropriate resolution by number. The
possible resolutions are:

@table @asis
@item right: drop
@itemx left: drop
Resolve one side of a duplicate name conflict by dropping it.

@itemx drop
Resolve an orphaned node conflict by dropping it.

@item right: rename
@itemx left: rename
Resolve one side of a duplicate name conflict by specifying a new name.

@item rename
Resolve an orphaned node conflict by specifying a new name.

@item right: right file
@itemx right: left file
@itemx left: right file
@itemx left: left file
Resolve one side of a duplicate name conflict by specifying a file.

The other side must be dropped or renamed.

@itemx left file
Resolve a content conflict by specifying a file. The file defaults to
the current workspace file.

@item right: keep
@itemx left: keep
Resolve one side of a duplicate name conflict by keeping it as is.

The other side must be dropped or renamed.

@item right: ediff
@itemx left: ediff
Resolve one side of a duplicate name conflict by ediff. This brings up
an ediff merge of the two files, and saves the result in the
resolution file area.

The other side must be dropped or renamed.

@item ediff
Resolve a content conflict via ediff. This brings up an ediff merge of
the two files, and saves the result in the resolution file area.

@end table

See @xref{mtn conflicts keys}, for a summary of key bindings.

@node mtn command line
@chapter mtn command line
Sometimes, especially over NFS, the Emacs DVC interface can be
painfully slow, and it is appropriate to use the mtn command line
instead.

Other times, the mtn command line is just simpler.

So we list the most useful mtn commands here. See the monotone command
line help or manual for more information.

@table @code
@item status
@code{mtn status}

@item commit
@code{mtn commit --message="<message>"}

@code{mtn commit --message-file=_MTN/log}

@item rename
@code{mtn rename <file> <new-file>}

@item update
@code{mtn update --move-conflicting-paths}

@end table

@node Common Errors and Solutions
@chapter Common Errors and Solutions

@menu
* Attach blocked by unversioned path::
* Revision id does not match conflict file::
@end menu

@node Attach blocked by unversioned path
@section Attach blocked by unversioned path
Problem: When attempting to update a directory, this warning appears:

@example
$ mtn update
 ...
mtn: warning: attach node 2147486644 blocked by unversioned path '<file path>'
mtn: misuse: 1 workspace conflict
@end example

Explanation: "Unversioned path" means the indicated file is not in the
current revision, however the file already exists on the disk. The
revision you are updating to contains the file, but it can't be
updated because it would overwrite the unknown file on the disk

Solution: Delete the indicated files from the disk and retry the
update, or specify the @command{--move-conflicting-paths} option.

@node Revision id does not match conflict file
@section Revision id does not match conflict file
Problem: When attempting to propagate from one branch to another, this message appears:

@example
$ mtn: propagating common.main -> common.work_user
  mtn: [left]  48b675060af47a02bc6f773bd63647726f96cbd5
  mtn: [right] 94ffd0b529dfb44c3ab122fe6c514b5f2e857104
  mtn: misuse: left revision id does not match conflict file
@end example

Explanation: It means you have some conflict files left over from a
previous propagation or merge.

Solution: In a buffer showing the ``from'' workspace, run: M-x
xmtn-conflicts-clean.  Repeat in the ``to'' workspace, then propagate
again.

@node GNU Free Documentation License,  , Common Errors and Solutions, Top
@appendix GNU Free Documentation License

@include fdl.texinfo
@bye