--- a/README_REPOSITORY Sat Nov 29 19:21:32 2008 +0100
+++ b/README_REPOSITORY Sun Nov 30 12:25:54 2008 +0100
@@ -7,36 +7,38 @@
Mercurial http://www.selenic.com/mercurial belongs to a new generation
of source code management systems, following the paradigm of
"distributed version control". Compared to the old centralized model
-of CVS/SVN, this gives considerable more power and freedom in
+of CVS or SVN, this gives considerable more power and freedom in
organizing the flow of changes, both between individual developers and
designated pull/push areas that are shared with others.
More power for the user also means more responsibility! Due to its
decentralized nature, changesets that have been published once,
-e.g. via push to a shared repository that is visible on the net,
+e.g. via "push" to a shared repository that is visible on the net,
cannot be easily retracted from the public again. Regular Mercurial
operations are strictly monotonic, where changset transactions are
-only added, but never deleted. There are special tools to "repair"
+only added, but never deleted. There are special tools to manipulate
individual repositories via non-monotonic actions, but this does not
-yet retrieve unwanted changesets that have escaped into the public.
+yet retrieve any changesets that have escaped into the public by
+accident.
-Only global operations like pull/push, unbundle/bundle etc. fall into
-this critical category; incoming/outgoing or in/out may help to
-inspect changesets before exchanging them globally. Anything else in
-Mercurial is local to the user's repository clone (including
-commit/update/merge etc.) and is in fact much simpler and safer to use
-than the corresponding operations of CVS or SVN.
+Only global operations like "pull" / "push", "unbundle" / "bundle"
+etc. fall into this critical category. Note that "incoming" /
+"outgoing" allow to inspect changesets before exchanging them
+globally. Anything else in Mercurial is local to the user's
+repository clone (including "commit", "update", "merge" etc.) and is
+in fact much simpler and safer to use than the corresponding
+operations of CVS or SVN.
Initial configuration
=====================
-Never use any Mercurial version before 1.0! At the moment, versions
-1.0, 1.0.1 and 1.0.2 all work equally well.
+Always use Mercurial version 1.0 or later, such as 1.0.1 or 1.0.2.
+The old 0.9.x versions do not work in a multi-user environment with
+shared file spaces.
-The public pull area of the Isabelle repository can be cloned like
-this:
+The official Isabelle repository can be cloned like this:
hg clone http://isabelle.in.tum.de/repos/isabelle
@@ -46,7 +48,7 @@
added to isabelle/.hg/hgrc, but note that hgrc files are never copied
by another clone operation!
-There is also ~/.hgrc for per-user Mercurial configuration. The
+There is also $HOME/.hgrc for per-user Mercurial configuration. The
initial configuration should include at least an entry to identify
yourself. For example, something like this in /home/wenzelm/.hgrc:
@@ -54,16 +56,16 @@
username = wenzelm
Failing to configure the username correctly makes the system invent
-funny machine names that may persist eternally in the flow of
-changesets.
+funny machine names that may persist indefinitely in the public flow
+of changesets.
In principle, user names can be chosen freely, but for longterm
committers of the Isabelle repository the obvious choice is to keep
with the old CVS naming scheme.
-There are other useful configuration to go into ~/.hgrc, e.g. defaults
-for common commands:
+There are other useful configuration to go into $HOME/.hgrc,
+e.g. defaults for common commands:
[defaults]
log = -l 10
@@ -86,52 +88,57 @@
The entry point http://isabelle.in.tum.de/repos/isabelle is world
readable, both via plain web browsing and the hg client as described
above. Anybody can produce a clone, change it arbitrarily, and then
-use regular mechanisms of Mercurial to report changes "upstream", say
+use regular mechanisms of Mercurial to report changes upstream, say
via e-mail to someone with write access to that file space. It is
-also quite easy to publish changed clones again on the web, using hg
-serve, or the hgweb.cgi or hgwebdir.cgi scripts that are included in
-the Mercurial distribution.
+also quite easy to publish changed clones again on the web, using the
+adhoc command "hg serve -v", or the hgweb.cgi or hgwebdir.cgi scripts
+that are included in the Mercurial distribution.
-This downstream/upstream mode of operation is quite common in the
+The downstream/upstream mode of operation is quite common in the
distributed version control community, and works well for occasional
changes produced by anybody out there. Of course, upstream
maintainers need to review and moderate changes being proposed, before
pushing anything onto the official Isabelle repository at TUM.
-Direct pull/push access requires an account at TUM, with properly
-configured ssh access to the local machines (e.g. macbroy20,
-atbroy100).
+Write access to the Isabelle repository requires an account at TUM,
+with properly configured ssh access to the local machines
+(e.g. macbroy20, atbroy100). You also need to be a member of the
+"isabelle" Unix group.
-The simple wrapper script /home/isabelle/mercurial/bin/hg provides a
-uniform view on the different Linux installations on the local
-network. Thus it is advisable to add that directory to the shell PATH
-of the account at TUM:
+Sharing a locally modified clone then works as follows, using your
+user name instead of "wenzelm":
+
+ hg out ssh://wenzelm@atbroy100//home/isabelle-repository/repos/isabelle
- PATH="/home/isabelle/mercurial/bin:$PATH"
-
-Now a clone of the shared push/pull area can be produced like this,
-using your user name instead of "wenzelm":
+In fact, the "out" or "outgoing" command performs only a dry run: it
+displays the changesets that would get published. An actual "push",
+with a lasting effect on the Isabelle repository, works like this:
- hg clone ssh://wenzelm@atbroy100//home/isabelle-repository/repos/isabelle
+ hg push ssh://wenzelm@atbroy100//home/isabelle-repository/repos/isabelle
+
-In fact, the only difference to the previous clone of
-http://isabelle.in.tum.de/repos/isabelle is a different default
-pull/push path in isabelle/.hg/hgrc:
+Default paths for push and pull can be configure in isabelle/.hg/hgrc,
+for example:
[paths]
default = ssh://wenzelm@atbroy100//home/isabelle-repository/repos/isabelle
-This means an earlier pull-only clone can be changed into a pull/push
-version by editing this single line of the internal repository
-configuration.
+Now "hg pull" or "hg push" will use that shared file space, unless a
+different URL is specified explicitly.
+
+When cloning a repository, the default path is set to the initial
+source URL. So we could have cloned via that ssh URL in the first
+place, to get exactly to the same point:
+
+ hg clone ssh://wenzelm@atbroy100//home/isabelle-repository/repos/isabelle
Content discipline
==================
-Old-style centralized version control is occasionally compared with a
-"library where everybody scribbles into the books". Or seen the other
+Old-style centralized version control is occasionally compared to "a
+library where everybody scribbles into the books". Or seen the other
way round, the centralized model discourages individual
experimentation (with local branches etc.), because everything is
forced to happen on a shared file space. With Mercurial, arbitrary
@@ -168,7 +175,7 @@
The usual changelog presentation style for the Isabelle repository
admits log entries that consist of several lines, but without the
- special head line that is used in Mercurial projects elsewhere.
+ special headline that is used in Mercurial projects elsewhere.
Since some display styles strip newlines from text, it is
advisable to separate lines via punctuation, and not rely on
two-dimensional presentation too much.
@@ -178,13 +185,14 @@
=============================================
Compared to a proper distribution or development snapshot, a
-repository version of Isabelle lacks proper version identifiers in
-various places, and some components produced by Admin/build. After
-applying that script with suitable options, the regular user
-instructions for building and running Isabelle from sources apply.
+repository version of Isabelle lacks textual version identifiers in
+some sources and scripts, and various components produced by
+Admin/build are missing. After applying that script with suitable
+arguments, the regular user instructions for building and running
+Isabelle from sources apply.
-Needless to say, the results from the build process must not be
-committed back into the repository!
+Needless to say, the results from the build process must not be added
+to the repository!
-Makarius 29-Nov-2008
+Makarius 30-Nov-2008