Changeset 959

Timestamp:

Dec 7, 2009, 5:54:37 AM (13 years ago)

Author:

Peter Johansson

Message:

documenting svndigest-copy-cache. closes #380

File:

• trunk/doc/readme.txt (modified) (2 diffs)

trunk/doc/readme.txt

@@ -97 +97 @@
 
 To avoid retrieving the same data repeatedly from the repository,
-statistics is cahed in files located in `.svndigest`. Subsequent
+statistics is cached in files located in `.svndigest`. Subsequent
 svndigest runs read the cache files and retrieve information from the
 repository only for the revisions that have been committed since the
@@ -198 +198 @@
   * Create the plots and HTML presentation.
 
+= Copy Cache =
+
+As explained above, statistics are cached during a run and svndigest
+only communicates with the server to retrieve statistics of the
+activity since last run. Subsequent runs are much faster why it is
+prefereble to run svndigest in a wc with recent cache available.
+
+Sometimes it is useful to copy the cache from one wc to another, and
+an easy way to do this is to use the tool `svndigest-copy-cache`,
+which is shipped with svndigest. A common use case is when creating,
+say, a release branch from the trunk, in which case you likely will
+have two working copies to follow the two branches. If you want to run
+svndigest on both of them and you want to avoid the first expensive
+run (without cache) you can copy the cache from the trunk wc to the
+release-branch wc.
+
+As explained in the caching section, it is important that the cache
+reflects a revision that belong to the history of the wc. So, for
+example, when creating a branch it is crucial to copy the cache from
+the trunk wc to the new branch wc before running svndigest on trunk
+wc. Otherwise the cache will contain information about changesets that
+were committed after the new branch were forked out. This will not
+only be untrue as these changesets are not in the line of history of
+the branch, but it will also cause problems for svndigest when
+calculating the statistics of the most recent revisons and result is
+undefined due to inconsistency between the cache and the log. For an
+example of how `svndigest-copy-cache` may be used please refer to the
+ReleaseProcedure of svndigest.
+
+`svndigest-copy-cache` copies the cache file from `ROOT` tree to the
+corresponding directory in `TARGET` tree. The tree structure of the
+two working copies must be identical because `svndigest-copy-cache`
+will not create any directories in `TARGET` tree except that
+`.svndigest` directories are created when necessary.
+
+Also, `svndigest-copy-cache` is ignorant about svn wc and will parse
+through `ROOT` directory and all its sub-directories ,looking for
+svndigest cache files, regardless whether they belong to the same svn
+working copy or not. Therefore, having other svn wc in subdirectories
+of `ROOT` might give an unexpected result.