.\" -*- nroff-fill -*-
.\" $Id: mklinks.1,v 1.7 2005/07/13 04:10:34 grog Exp $
.Dd October 8, 2004
.Os
.Dt mklinks 1
.Sh NAME
.Nm mklinks
.Nd create, merge or update related directory hierarchies.
.Sh SYNOPSIS
.Nm
.Op Fl flags
.Ar source-dir dest-dir
.Nm
command
.Op Fl flags
.Ar source-dir dest-dir
.Sh DESCRIPTION
.Nm
provides a number of functions for manipulating hierarchies of similar files.
The original purpose was to maintain similar trees of source code, but it can
also be used for binary files.  In all cases, it leaves 
.Ar source-dir
unchanged and (possibly) modifies
.Ar dest-dir .
.Pp
By default,
.Nm
creates links between the source and destination directories.  In the case of
symbolic links, the link is from the destination directory to the source
directory.
.P
The following flags change the functions that
.Nm 
performs:
.Bl -tag -width indent
.It Fl r
Remove files from
.Ar dest-dir
which exist in
.Ar src-dir .
.It Fl R
Remove files from
.Ar dest-dir
which exist in
.Ar src-dir .
Additionally, if any directory becomes empty, remove that directory.
.El
.Pp
The following flags modify the way
.Nm
performs these functions:
.Bl -tag -width indent
.It Fl c
Don't compare files with different timestamps before prompting.
.It Fl d
Do a diff | less to screen before prompting for replacement.  See also the 
.Fl w
flag.
.It Fl D
Don't create directories if they're not present.
.It Fl k
Keep files with different contents.
.It Fl n
Prompt to replace files with newer versions.
.It Fl N
Replace files with newer versions unconditionally.
.It Fl q
Prompt before linking files with same timestamps.
.It Fl s
Create symlinks (bitmapped flag).  The bits have the following meanings:
.Bl -tag -width 4n -offset indent -compact
.It Sy 1
Create a symlink if the source file was a symlink.
.It Sy 2
Create a symlink if source file was a regular file.
.It Sy 4
Create a symlink if source file was a directory.
.It Sy 8
Link to the original source file, not a source symlink.
.El
When deleting, this flag has no effect.
.It Fl u
Don't replace identical files (with same content and date).
.It Fl v Op num
Specify verbosity.
.Bl -tag -width 4n -offset indent -compact
.It Sy 0
Don't produce any output except for error messages and any information requested
with the
.Fl d ,
.Fl n ,
.Fl q and
.Fl w
flags.  This is the default value.
.It Sy 1
Print information about files not copied or linked, and about directories
created.  This is the default value if
.Ar num
is omitted.
.It Sy 2
Additionally to 1, print information about each file examined.  Each line starts
with a series of characters for easy recognition.
.It Sy 3
Additionally to 2, print information about whether files have same contents or
not.
.El
.It Fl w
Do a diff -w | less to screen before prompting for replacement.
.It Fl X
Don't create a link if the destination file does not exist.
.It Fl z
Display the actions, but don't perform them.  This should be used in combination
with the
.Fl v
flag.
.El
.Pp
The following commands set combinations of the above flags to perform typical
functions.  Each may be modified by any of the preceding flags.  Note that the
flags must be placed after the command in order to have any effect.
.Bl -tag -width indent
.It Nm clone
Create a copy of
.Ar source-dir
in
.Ar dest-dir .
Unless other flags follow, all directories in 
.Ar dest-dir
will be distinct from the directories in
.Ar source-dir ,
but the files will be linked to the same file if
.Ar source-dir
and 
.Ar dest-dir
are on the same file system; otherwise the files in
.Ar dest-dir
will be symbolic links to the files in
.Ar source-dir .
.It Nm merge
Merge two trees.  For each file in the destination directory which is also in
the source directory, remove the file from the destination directory and replace
it with a link (by default a hard link where possible) to the file in the source
directory.
.It Nm rm
Remove all files in
.Ar dest-dir
which have a corresponding file in
.Ar source-dir .
By default files which differ will not be deleted; use a combination of the
.Fl c ,
.Fl d ,
.Fl n ,
.Fl N
or
.Fl p
flags to compare the files.
.Pp
By default, 
.Nm rm
does not remove directories which become empty.  Append the
.Fl R
flag to remove directories as well.
.It Nm update
Replace older versions of files in
.Ar dest-dir
with the versions in
.Ar source-dir .
Unless other flags follow, all directories in 
.Ar dest-dir
will be distinct from the directories in
.Ar source-dir ,
but the files will be linked to the same file if
.Ar source-dir
and 
.Ar dest-dir
are on the same file system; otherwise the files in
.Ar dest-dir
will be symbolic links to the files in
.Ar source-dir .
.El 
.\" The following requests should be uncommented and
.\" used where appropriate.
.\" .Sh IMPLEMENTATION NOTES
.\" This next request is for sections 2, 3 and 9 function
.\" return values only.
.\" .Sh RETURN VALUES
.\" This next request is for sections 1, 6, 7 and 8 only.
.\" .Sh ENVIRONMENT
.\" .Sh FILES
.\" .Sh EXAMPLES
.\" This next request is for sections 1, 6, 7, 8 and 9 only
.\"     (command return values (to shell) and
.\"     fprintf/stderr type diagnostics).
.\" .Sh DIAGNOSTICS
.\" .Sh COMPATIBILITY
.\" This next request is for sections 2, 3 and 9 error
.\"     and signal handling only.
.\" .Sh ERRORS
.\" .Sh SEE ALSO
.\" .Sh STANDARDS
.\" .Sh HISTORY
.Sh AUTHORS
Greg Lehey <grog@lemis.com>
.\" .Sh BUGS