\input texinfo @c -*- texinfo -*- 
@c $Id: cvsfs.texi,v 1.6 2005/11/16 21:18:08 stesie Exp $
@c %**start of header
@setfilename cvsfs.info
@include version.texi
@settitle @sc{cvsfs} virtual filesystem translator
@syncodeindex pg cp
@c %**end of header



@copying
Copyright @copyright{} 2004, 2005 by Stefan Siegl, Germany

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
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 quotation
@end copying

@titlepage
@title @sc{cvsfs}
@subtitle (virtual CVS filesystem translator for the GNU Hurd)
@subtitle for version @value{VERSION}, @value{UPDATED}
@author Stefan Siegl (@email{stesie@@brokenpipe.de})

@page
@vskip 0pt plus 1filll

@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top cvsfs virtual filesystem translator
@end ifnottex

This manual documents version @value{VERSION} of the @sc{cvsfs}
virtual filesystem translator.


@insertcopying

@menu
* Overview::                    On how to get in touch.
* Authentication::              Using username/password to log in.
* Remote Shell Connections::    Using rsh or ssh to connect to the cvs host.
* Browsing Local Repositories:: Browsing a local cvs repository with cvsfs
* File Status Information::     File's status and access permissions.
* Write Support::               On writing to cvsfs mounted modules.
* Copying This Manual::
* Index::
@end menu

@c ---------------------------------------------------------------------------
@node Overview
@chapter Overview
@cindex Overview

This chapter is for people who have never heard of or at least used @sc{cvsfs},
and perhaps have not get in touch with version control software before.

If you are already familiar with CVS you probably will not feel 
uncomfortable with @sc{cvsfs} right from the start.

@menu
* What is cvsfs?::                    What you can do with cvsfs
* What is cvsfs not?::                Things you cannot solve with cvsfs
* Sample::                            Tour of basic usage
@end menu

@c ---------------------------------------------------------------------------
@node What is cvsfs?
@section What is cvsfs?
@cindex What is cvsfs?
@cindex Introduction to cvsfs

@sc{cvsfs} is a so called translator for the GNU Hurd operating system, 
enabling to bind remotely located CVS modules right into your local
file system tree. It allows to view version controlled files right
the same way you look at ordinary (locally stored) ones. 

This software is still being developed, therefore please do not expect
a program without any bugs. 

Mounting a CVS module allows you to view your (or others') version controlled
files with the programs you are used to. This is, you can view any file,
checked into CVS, using your favourite text editor (aka emacs) without
having to check the
whole module out.  Thus you save the time and network bandwidth necessary
to do a full checkout as @sc{cvsfs} downloads the directory tree only. 
Each file's content is only downloaded if necessary, i.e. if you try to read
it.

@c TODO if cvsfs is little older, perhaps mention it's history

@cindex Source, getting cvsfs sources
You can get @sc{cvsfs} in a variety of ways, including
free download from the internet.  For more information on
downloading @sc{cvsfs} and other @sc{cvsfs} topics, see:

@example
@url{http://savannah.nongnu.org/projects/hurdextras/}
@end example

@cindex Mailing list
@cindex List, mailing list
There is a mailing list @email{hurdextras-hackers@@nongnu.org},
which may be used for discussions concerning @sc{cvsfs}.  
To subscribe or unsubscribe write to
@email{hurdextras-hackers-request@@nongnu.org}. 

@c ---------------------------------------------------------------------------
@node What is cvsfs not?
@section What is cvsfs not?
@cindex What is cvsfs not?

@sc{cvsfs} can do a lot of things for you, but it does
not try to be everything for everyone.

@table @asis
@cindex Write support
@item @sc{cvsfs} does not support writing.

Though you might want it to have write support I consider this
feature useless.  What is the advantage of being able to change
files in the cvsfs virtual filesystem, having to write a log message
to some obscure target?

I think it would not make things easier compared to the common
@code{cvs ci}?

@item @sc{cvsfs} is not a replacement for @code{cvs}.

Even though it might look to you as such, but it should not.  There
are quite huge differencies between @sc{cvsfs} and common cvs.
@sc{cvsfs} aims to be a little tool, allowing to hit and view just a few files
out of a nested cvs directory tree.  However cvs is thought to check things
out in order to edit or compile them, i.e. allowing to write,
etc.  That said, it might look more reasonable to compare it with viewcvs
or similar packages, however these allow to view files over the web only.

@end table

@c ---------------------------------------------------------------------------
@node Sample
@section Sample
@cindex Example of a work-session
@cindex Getting started

As a way of introducing @sc{cvsfs}, we'll go through a
typical work-session using @sc{cvsfs}.  Suppose you
want to view the CVS repository of wsdebug, a debugger for
the whitespace programming language.

@cindex Translators, concept
@cindex Translators, setting up
@cindex settrans
The first thing to
understand is the GNU Hurd's concept of translators. A so called
translator is a userspace program, translating e.g. network stored
data to local filesystem nodes.  Those translators are set up using
@code{settrans}.

Assuming you have created an empty directory called wsdebug-src,
you need to enter

@example
settrans -a wsdebug-src cvsfs cvs.berlios.de /cvsroot/wsdebug wsdebug
@end example

to set up an active translator, mapping the CVS module 
@code{wsdebug} from below @code{/cvsroot/wsdebug} stored on
@code{cvs.berlios.de} to the specified local directory.

Now you can enter and browse the wsdebug-src directory the way 
you are used to. For example you can @code{cd wsdebug-src}, do
a @code{ls} to show which files are available and choose one file
to open with the text editor of your choice. You can even use
graphical file managers like @code{xfm} to view the directory tree.

@cindex Translators, killing
@cindex getting rid of cvsfs instance
@cindex Translators, getting rid
In order to get rid of the translator leave the wsdebug-src/
directory tree and enter

@example
settrans -g wsdebug-src
@end example

@c ---------------------------------------------------------------------------
@node Authentication
@chapter Authentication
@cindex Authentication
@cindex Username
@cindex Password, supplied when authenticating

@sc{cvsfs} by default uses the omnipresent CVS pserver protocol to
connect to the specified CVS remote host.  This protocol requires
to supply login information (thus user-id and password) right after
connecting.

@cindex .cvspass file
@cindex anonymous
@cindex login, username
@cindex login, anonymously
As you probably will use @sc{cvsfs} to mainly browse 
CVS repositories of open source projects you are interested in,
anonymously, @sc{cvsfs} defaults to supply @code{anonymous} as
your user-id.  If not otherwise specified in your @code{.cvspass} file it
will use an empty password to log in.  This is what you probably want,
if you connect to repositories of sourceforge.net or the quite similar
developer.berlios.de.  However this is not what you might expect, if
you are very familiar with CVS which tends to supply your username, if
you don't tell it to use @code{anonymous}!

If you want to connect to a repository where you need to supply a
real user-id, you need to supply the @option{--user} option, followed
by the username of your choice.

Before establishing the host connection @sc{cvsfs} tries to scan your
@code{.cvspass} file for the password to be used when trying to 
authenticate.  If it cannot find the password file or the file simply
does not tell a suitable password, the translator will bark
and try logging in without a password (probably failing, if you
are not using anonymous login credentials).

@cindex homedir
@cindex /etc/passwd
@sc{cvsfs} looks for a @code{.cvspass} file in your home directory (as
specified in @code{/etc/passwd} file) by default.  If you - for whatever reason - want
it to read from an other password file,  supply it's directory using
the @option{--homedir} option.

@cindex Password, adding to .cvspass
If there is no entry for the CVSROOT of choice in your password file,
simply use CVS' @code{login} command.  For example, if you would like
to log into cvsfs's CVS repository using my credentials, do
something like that:

@example
$ cvs -d:pserver:stesie@@savannah.nongnu.org:/cvsroot/hurdextras login
CVS password: <password>
$ settrans -a cvsfs-src /sbin/cvsfs --user stesie \
           savannah.nongnu.org /cvsroot/hurdextras cvsfs
@end example

@c ---------------------------------------------------------------------------
@node Remote Shell Connections
@chapter Remote Shell Connections
@cindex Remote Shell Connections
@cindex pserver
@cindex CVS pserver
@cindex ssh
@cindex rsh
@cindex Shell Client
@cindex Remote Shell Client (rsh)

@sc{cvsfs} by default uses the pserver protocol to
connect to the specified CVS remote host.  This is what you probably
want to use, if you are not the developer of the project on which
sources you would like to glance at.  If you want to use @sc{cvsfs} to
view the source of a sourceforge hosted project you are contributing
to, you may want to use the @code{ssh} remote shell client to connect
(because the anonymous cvs server is commonly some hours behind, so
you will not see most recent changes).

In order to tell @sc{cvsfs} that you want a remote shell client to be used,
simply supply the @option{--remote} option when calling @code{settrans}.
However @sc{cvsfs} tends to use the ancient @code{rsh} shell client,
just like CVS does.  If you want to use @code{ssh}, you need to supply
@option{--remote=ssh} (or abbreviated: @option{-rssh}) when launching.

@sc{cvsfs} will use @code{anonymous} as the user-id to the remote
shell client, if you do not specify your real id using
@option{--user} option, therefore be careful when you are too much
used to using cvs.

@cindex Password, ssh not asking
@cindex authorized_keys
Please consider that ssh, or whichever remote shell client you use,
cannot ask you for your password, since translators are not connected
to a terminal on the Hurd.  Therefore you need to configure it to
put you straight to the command prompt when calling it something like 
@code{ssh -l USERNAME HOSTNAME}.  To allow this, you probably want to
create a @code{$HOME/.ssh/authorized_keys} file on the remote host.

@c ---------------------------------------------------------------------------
@node Browsing Local Repositories
@chapter Browsing Local Repositories
@cindex Browsing Local Repositories

Apart from using @sc{cvsfs} to browse remotely located CVS repositories,
using either pserver protocol or the :ext: method, you may even use it
to browse CVS repositories which are located on your computer or
otherwise mounted into your filesystem. 

In order to make @sc{cvsfs} behaving this way, either start it with
@code{localhost} as the @option{HOSTNAME} or specify the
@option{--local} option.  Mind that you must not omit the
@option{HOSTNAME} argument in any case, even the latter one.  The argument is
just not going to be evaluated if the @option{--local} option is present.

As an exampe, if you would like, to browse the CVSROOT pseudo module
of your local host's CVS repository (located at
@code{/var/lib/cvs}) type something like this:

@example
$ settrans -a test-node/ /sbin/cvsfs --local - /var/lib/cvs CVSROOT
@end example

You may now enter the directory @code{test-node/}, which allows you to
browse the CVSROOT module.

@c ---------------------------------------------------------------------------
@node File Status Information
@chapter File Status Information
@cindex File Status Information

In order to serve true information on each file's status (thus length
of file, timestamps as well as permissions) @sc{cvsfs} needs
to download this information from the CVS server.  However to retrieve
this, @sc{cvsfs} has to download the whole revision,
including it's content. 

Suppose you request an @code{ls -lR} from the top directory of the
mapped CVS module.  @sc{cvsfs} will need to download all the files to
provide the information to you, therefore being painfully slow.

There are two possibilities towards omitting that:

@table @asis
@item do not request stats unless you need to

This is probably the easiest possibility, however this involves, that
you probably cannot use graphical file managers like xfm or gmc, as
those call @code{stat} function automatically.  Furthermore you will
need to take care of @code{ls} tending to do coloured output, which
will check for executable flags, etc. as well.

@item supply @option{--nostats} option to @sc{cvsfs}

If you supply @option{--nostats} option to this translator you will
never wait for @sc{cvsfs} to download for simply filling stats
information. However all files will be reported to be zero bytes long,
have the current time as their timestamps and have only reading
permissions set. 

@sc{cvsfs} has no possibility to figure out whether a particular file
is executable.  Therefore if you want to run an executable from a
virtually included CVS module you need to omit using
@option{--nostats}. 

@end table

On the whole you should get used to using @option{--nostats} as you
probably want to just read through one or two files; opposed to using
@sc{cvsfs} to serve files to compile a source package.

@c ---------------------------------------------------------------------------
@node Write Support
@chapter Write Support
@cindex Write Support

@sc{cvsfs} by definition is to be a tool, allowing you to hit and view
a few files out of a huge, nested cvs controlled directory tree.  It
is not the intention to write another @code{cvs} client, allowing to
check files in.

@cindex commit
Actually the question is, is there a clever way to allow easier
check-in than the way common cvs does?  The filesystem related
approach would be to supply a @code{/commit} file somewhere, where you
need to supply your log-message to.  But that seems to be even
clumpsier than the common @code{ci} command of cvs.

@cindex unionfs
@cindex shadowfs
One thing that might be worth considering is to allow creating
temporary files in the mapped CVS module, thus allowing to ./configure
and compile within such a directory.  However I suppose using
@code{unionfs}, @code{shadowfs} or something similar would make
more sense.  The only
problem with this is, that @code{unionfs} does not seem to be far
enough to do that job now.

You might want to consider, that most packages can be configured
outside the source directory.  For example @sc{cvsfs} is able to do so.

@c ---------------------------------------------------------------------------
@node Copying This Manual
@appendix Copying This Manual

@menu
* GNU Free Documentation License::    License for copying this manual.
@end menu

@include fdl.texi

@c ---------------------------------------------------------------------------
@node Index
@unnumbered Index

@printindex cp
@bye
