README_REPOSITORY
changeset 28913 86ed1c86e0ef
parent 28910 5c712e46988f
child 28917 20f43e0e0958
     1.1 --- a/README_REPOSITORY	Sat Nov 29 19:21:32 2008 +0100
     1.2 +++ b/README_REPOSITORY	Sun Nov 30 12:25:54 2008 +0100
     1.3 @@ -7,36 +7,38 @@
     1.4  Mercurial http://www.selenic.com/mercurial belongs to a new generation
     1.5  of source code management systems, following the paradigm of
     1.6  "distributed version control".  Compared to the old centralized model
     1.7 -of CVS/SVN, this gives considerable more power and freedom in
     1.8 +of CVS or SVN, this gives considerable more power and freedom in
     1.9  organizing the flow of changes, both between individual developers and
    1.10  designated pull/push areas that are shared with others.
    1.11  
    1.12  More power for the user also means more responsibility!  Due to its
    1.13  decentralized nature, changesets that have been published once,
    1.14 -e.g. via push to a shared repository that is visible on the net,
    1.15 +e.g. via "push" to a shared repository that is visible on the net,
    1.16  cannot be easily retracted from the public again.  Regular Mercurial
    1.17  operations are strictly monotonic, where changset transactions are
    1.18 -only added, but never deleted.  There are special tools to "repair"
    1.19 +only added, but never deleted.  There are special tools to manipulate
    1.20  individual repositories via non-monotonic actions, but this does not
    1.21 -yet retrieve unwanted changesets that have escaped into the public.
    1.22 +yet retrieve any changesets that have escaped into the public by
    1.23 +accident.
    1.24  
    1.25 -Only global operations like pull/push, unbundle/bundle etc. fall into
    1.26 -this critical category; incoming/outgoing or in/out may help to
    1.27 -inspect changesets before exchanging them globally.  Anything else in
    1.28 -Mercurial is local to the user's repository clone (including
    1.29 -commit/update/merge etc.) and is in fact much simpler and safer to use
    1.30 -than the corresponding operations of CVS or SVN.
    1.31 +Only global operations like "pull" / "push", "unbundle" / "bundle"
    1.32 +etc. fall into this critical category.  Note that "incoming" /
    1.33 +"outgoing" allow to inspect changesets before exchanging them
    1.34 +globally.  Anything else in Mercurial is local to the user's
    1.35 +repository clone (including "commit", "update", "merge" etc.) and is
    1.36 +in fact much simpler and safer to use than the corresponding
    1.37 +operations of CVS or SVN.
    1.38  
    1.39  
    1.40  Initial configuration
    1.41  =====================
    1.42  
    1.43 -Never use any Mercurial version before 1.0!  At the moment, versions
    1.44 -1.0, 1.0.1 and 1.0.2 all work equally well.
    1.45 +Always use Mercurial version 1.0 or later, such as 1.0.1 or 1.0.2.
    1.46 +The old 0.9.x versions do not work in a multi-user environment with
    1.47 +shared file spaces.
    1.48  
    1.49  
    1.50 -The public pull area of the Isabelle repository can be cloned like
    1.51 -this:
    1.52 +The official Isabelle repository can be cloned like this:
    1.53  
    1.54    hg clone http://isabelle.in.tum.de/repos/isabelle
    1.55  
    1.56 @@ -46,7 +48,7 @@
    1.57  added to isabelle/.hg/hgrc, but note that hgrc files are never copied
    1.58  by another clone operation!
    1.59  
    1.60 -There is also ~/.hgrc for per-user Mercurial configuration.  The
    1.61 +There is also $HOME/.hgrc for per-user Mercurial configuration.  The
    1.62  initial configuration should include at least an entry to identify
    1.63  yourself.  For example, something like this in /home/wenzelm/.hgrc:
    1.64  
    1.65 @@ -54,16 +56,16 @@
    1.66    username = wenzelm
    1.67  
    1.68  Failing to configure the username correctly makes the system invent
    1.69 -funny machine names that may persist eternally in the flow of
    1.70 -changesets.
    1.71 +funny machine names that may persist indefinitely in the public flow
    1.72 +of changesets.
    1.73  
    1.74  In principle, user names can be chosen freely, but for longterm
    1.75  committers of the Isabelle repository the obvious choice is to keep
    1.76  with the old CVS naming scheme.
    1.77  
    1.78  
    1.79 -There are other useful configuration to go into ~/.hgrc, e.g. defaults
    1.80 -for common commands:
    1.81 +There are other useful configuration to go into $HOME/.hgrc,
    1.82 +e.g. defaults for common commands:
    1.83  
    1.84    [defaults]
    1.85    log = -l 10
    1.86 @@ -86,52 +88,57 @@
    1.87  The entry point http://isabelle.in.tum.de/repos/isabelle is world
    1.88  readable, both via plain web browsing and the hg client as described
    1.89  above.  Anybody can produce a clone, change it arbitrarily, and then
    1.90 -use regular mechanisms of Mercurial to report changes "upstream", say
    1.91 +use regular mechanisms of Mercurial to report changes upstream, say
    1.92  via e-mail to someone with write access to that file space.  It is
    1.93 -also quite easy to publish changed clones again on the web, using hg
    1.94 -serve, or the hgweb.cgi or hgwebdir.cgi scripts that are included in
    1.95 -the Mercurial distribution.
    1.96 +also quite easy to publish changed clones again on the web, using the
    1.97 +adhoc command "hg serve -v", or the hgweb.cgi or hgwebdir.cgi scripts
    1.98 +that are included in the Mercurial distribution.
    1.99  
   1.100 -This downstream/upstream mode of operation is quite common in the
   1.101 +The downstream/upstream mode of operation is quite common in the
   1.102  distributed version control community, and works well for occasional
   1.103  changes produced by anybody out there.  Of course, upstream
   1.104  maintainers need to review and moderate changes being proposed, before
   1.105  pushing anything onto the official Isabelle repository at TUM.
   1.106  
   1.107  
   1.108 -Direct pull/push access requires an account at TUM, with properly
   1.109 -configured ssh access to the local machines (e.g. macbroy20,
   1.110 -atbroy100).
   1.111 +Write access to the Isabelle repository requires an account at TUM,
   1.112 +with properly configured ssh access to the local machines
   1.113 +(e.g. macbroy20, atbroy100).  You also need to be a member of the
   1.114 +"isabelle" Unix group.
   1.115  
   1.116 -The simple wrapper script /home/isabelle/mercurial/bin/hg provides a
   1.117 -uniform view on the different Linux installations on the local
   1.118 -network.  Thus it is advisable to add that directory to the shell PATH
   1.119 -of the account at TUM:
   1.120 +Sharing a locally modified clone then works as follows, using your
   1.121 +user name instead of "wenzelm":
   1.122 +
   1.123 +  hg out ssh://wenzelm@atbroy100//home/isabelle-repository/repos/isabelle
   1.124  
   1.125 -  PATH="/home/isabelle/mercurial/bin:$PATH"
   1.126 -
   1.127 -Now a clone of the shared push/pull area can be produced like this,
   1.128 -using your user name instead of "wenzelm":
   1.129 +In fact, the "out" or "outgoing" command performs only a dry run: it
   1.130 +displays the changesets that would get published.  An actual "push",
   1.131 +with a lasting effect on the Isabelle repository, works like this:
   1.132  
   1.133 -  hg clone ssh://wenzelm@atbroy100//home/isabelle-repository/repos/isabelle
   1.134 +  hg push ssh://wenzelm@atbroy100//home/isabelle-repository/repos/isabelle
   1.135 +
   1.136  
   1.137 -In fact, the only difference to the previous clone of
   1.138 -http://isabelle.in.tum.de/repos/isabelle is a different default
   1.139 -pull/push path in isabelle/.hg/hgrc:
   1.140 +Default paths for push and pull can be configure in isabelle/.hg/hgrc,
   1.141 +for example:
   1.142  
   1.143    [paths]
   1.144    default = ssh://wenzelm@atbroy100//home/isabelle-repository/repos/isabelle
   1.145  
   1.146 -This means an earlier pull-only clone can be changed into a pull/push
   1.147 -version by editing this single line of the internal repository
   1.148 -configuration.
   1.149 +Now "hg pull" or "hg push" will use that shared file space, unless a
   1.150 +different URL is specified explicitly.
   1.151 +
   1.152 +When cloning a repository, the default path is set to the initial
   1.153 +source URL.  So we could have cloned via that ssh URL in the first
   1.154 +place, to get exactly to the same point:
   1.155 +
   1.156 +  hg clone ssh://wenzelm@atbroy100//home/isabelle-repository/repos/isabelle
   1.157  
   1.158  
   1.159  Content discipline
   1.160  ==================
   1.161  
   1.162 -Old-style centralized version control is occasionally compared with a
   1.163 -"library where everybody scribbles into the books".  Or seen the other
   1.164 +Old-style centralized version control is occasionally compared to "a
   1.165 +library where everybody scribbles into the books".  Or seen the other
   1.166  way round, the centralized model discourages individual
   1.167  experimentation (with local branches etc.), because everything is
   1.168  forced to happen on a shared file space.  With Mercurial, arbitrary
   1.169 @@ -168,7 +175,7 @@
   1.170  
   1.171      The usual changelog presentation style for the Isabelle repository
   1.172      admits log entries that consist of several lines, but without the
   1.173 -    special head line that is used in Mercurial projects elsewhere.
   1.174 +    special headline that is used in Mercurial projects elsewhere.
   1.175      Since some display styles strip newlines from text, it is
   1.176      advisable to separate lines via punctuation, and not rely on
   1.177      two-dimensional presentation too much.
   1.178 @@ -178,13 +185,14 @@
   1.179  =============================================
   1.180  
   1.181  Compared to a proper distribution or development snapshot, a
   1.182 -repository version of Isabelle lacks proper version identifiers in
   1.183 -various places, and some components produced by Admin/build.  After
   1.184 -applying that script with suitable options, the regular user
   1.185 -instructions for building and running Isabelle from sources apply.
   1.186 +repository version of Isabelle lacks textual version identifiers in
   1.187 +some sources and scripts, and various components produced by
   1.188 +Admin/build are missing.  After applying that script with suitable
   1.189 +arguments, the regular user instructions for building and running
   1.190 +Isabelle from sources apply.
   1.191  
   1.192 -Needless to say, the results from the build process must not be
   1.193 -committed back into the repository!
   1.194 +Needless to say, the results from the build process must not be added
   1.195 +to the repository!
   1.196  
   1.197  
   1.198 -Makarius 29-Nov-2008
   1.199 +Makarius 30-Nov-2008