[PATCH 2 of 3] largefiles: convert design.txt to reStructuredText; wrap to 75 columns

Greg Ward greg-hg at gerg.ca
Sun Oct 23 13:49:25 CDT 2011


# HG changeset patch
# User Greg Ward <greg at gerg.ca>
# Date 1319394328 14400
# Branch stable
# Node ID 7e40e247e0cf19110142000748fd17f3ddb8915c
# Parent  29ba04fdcd0dbd03aeedc1623e85b49ff522cbd5
largefiles: convert design.txt to reStructuredText; wrap to 75 columns

diff --git a/hgext/largefiles/design.txt b/hgext/largefiles/design.txt
--- a/hgext/largefiles/design.txt
+++ b/hgext/largefiles/design.txt
@@ -1,53 +1,61 @@
-= Design of largefiles extension =
+==============================
+Design of largefiles extension
+==============================
 
-See __init__.py for rationale and usage information. This file describes
-how largefiles works under the hood; it's for developers who need to
-understand largefiles rather than for users who need to use it.
+See ``__init__.py`` for rationale and usage information. This file
+describes how largefiles works under the hood; it's for developers who
+need to understand largefiles rather than for users who need to use
+it.
 
-== The largefile store ==
+The largefile store
+-------------------
 
-A largefile store, typically on a centralized server, has every past revision
-of every largefile. Each largefile revision is identified by its SHA-1 hash,
-and all interactions with the store take one of the following forms.
+A largefile store, typically on a centralized server, has every past
+revision of every largefile. Each largefile revision is identified by its
+SHA-1 hash, and all interactions with the store take one of the following
+forms.
 
--Download a particular largefile revision (by hash)
--Upload a particular largefile revision (by hash)
--Check if the store has a largefile with this hash
+  * download a particular largefile revision (by hash)
+  * upload a particular largefile revision (by hash)
+  * check if the store has a largefile with this hash
 
 largefiles stores can take one of two forms:
 
--Directories on a network file share
--Mercurial wireproto servers, either via ssh or http (hgweb)
+  * directories on a network file share
+  * Mercurial wireproto servers, either via ssh or http (hgweb)
 
-== The Local Repository ==
+The local repository
+--------------------
 
-The local repository has a largefile store in .hg/largefiles which holds a
-subset of the largefiles needed. When largefiles are downloaded from the
-central store, a copy is saved in this store.
+The local repository has a largefile store in ``.hg/largefiles`` which
+holds a subset of the largefiles needed. When largefiles are downloaded
+from the central store, a copy is saved in this store.
 
-== The User Cache ==
+The user cache
+--------------
 
 largefiles in a local repository store are hardlinked to files in the user
 cache. Before a file is downloaded we check if it is in the global cache,
 hard-linking to the local store if we find it.
 
-== Implementation Details ==
+Implementation details
+----------------------
 
-Each largefile has a standin file in .hglf/. The standin is tracked by
-Mercurial. The standin contains the SHA-1 hash of the largefile contents. When
-a largefile is added/removed/copied/renamed/etc the same operation is applied
-to the standin. Thus the history of the standin is the history of the
-largefile.
+Each largefile has a standin file in ``.hglf/``. The standin is tracked by
+Mercurial. The standin contains the SHA-1 hash of the largefile contents.
+When a largefile is added/removed/copied/renamed/etc the same operation is
+applied to the standin. Thus the history of the standin is the history of
+the largefile.
 
-For performance reasons, the contents of a standin are only updated before a
-commit.  Standins are added/removed/copied/renamed from add/remove/copy/rename
-Mercurial commands but their contents will not be updated. The contents of a
-standin will always be the hash of the largefile as of the last commit. To
-support some commands (revert) some standins are temporarily updated but will
-be changed back after the command is finished.
+For performance reasons, the contents of a standin are only updated before
+a commit. Standins are added/removed/copied/renamed from
+add/remove/copy/rename Mercurial commands but their contents will not be
+updated. The contents of a standin will always be the hash of the largefile
+as of the last commit. To support some commands (revert) some standins are
+temporarily updated but will be changed back after the command is finished.
 
-A Mercurial dirstate object tracks the state of the largefiles. The dirstate
-uses the last modified time and current size to detect if a file has changed
-(without reading the entire contents of the file). (Unfortunately, the use of
-dirstate limits largefiles to 2 GB. This will hopefully be fixed after
-Mercurial 2.0.)
+A Mercurial dirstate object tracks the state of the largefiles. The
+dirstate uses the last modified time and current size to detect if a file
+has changed (without reading the entire contents of the file).
+(Unfortunately, the use of dirstate limits largefiles to 2 GB. This will
+hopefully be fixed after Mercurial 2.0.)


More information about the Mercurial-devel mailing list