== Testing the code

"make" here in the test directory runs a complete set of regression
tests. It's what "make check" in the main directory redirects to.

Output from the tests is in TAP (Test Anything Protocol).  Test output
is normally filtered through test/tapview, which makes the test output
far less noisy, passing though only error indications. You can get the
raw TAP report at any time with "make tap".

On the 64-core 2.2GHz AMD Ryzen machine I use for development, a full
make check runs in about 14 seconds. Scale expectations appropriately
for your hardware.

If you get a failure on the repotool-initialize-cvs-git test, but
nowhere else, try updating your versions of CVS and cvs-fast-export
and trying again.

Test behavior is controlled by these variables:

REPOSURGEON: defaults to 'reposurgeon'

TESTOPT: Use this to pass in a command or option setting, such
as "set experimental".

QUIET: 0 (the default) allows display of a diff against the checkfile
when a test fails. When QUIET=1 the diff is suppressed; only the
TAP report line appears.

To run a single test:

------------------------------------------------------
$ cd test; ./singletest foo
------------------------------------------------------

will check the actual result of the script in foo.tst against its expected
output in foo.chk. A TAP "ok" line is good news.

The "liftcheck" script is useful for testing the conversion correctness
of a Subversion stream:

------------------------------------------------------
$ cd test; ./liftcheck foo.svn
------------------------------------------------------
   
An "ok" line means that a compare-all showed no errors or warnings.

To allow the code to emit a stack trace, set any log bit.

The script "delver" is available to run the Golang debugger,
dlv, on reposurgeon.

== Notes on the test machinery

A .fi extension means it's a git fast-import stream.  
A .svn extension means it's a Subversion repo dump.
A .chk extension means it's expected output from a test.
A .tst extension means it's a test driver script.

All reports from test scripts are in the form of TAP (Test Anything Protocol).

== The scripts

=== fi-to-fi

Builds a git repo from a fast-import stream on stdin, or streams an
existing repo to stdout. No report.

=== hg-to-fi

Builds an hg repo from a fast-import stream on stdin, or streams an
existing repo to stdout. No report.

=== svn-to-svn

Build a Subversion repo from a Subversion stream dump on stdin, or
dump an existing repo as a stream to stdout.  Can also be used to edit
a Subversion test load, regenerating its checksums. No report.

=== svn-to-git

Build a Subversion repo from a Subversion stream dump on stdin,
convert it to a local git repository, and stream the result to
standard output. Mainly a wrapper around git-svn, to be used
for comparison tests.  Can also be used to test against agito
and svn2git. No report.

To add a new tool for comparison, do something like:

------------------------------------------------------
$ git submodule add GIT-URL/foobar externals/foobar
$ git update submodules
------------------------------------------------------

from the repo root.

=== singletest === 

By default "singletest" script takes the stem of a .tst file name, captures
stdout and stderr, and diffs the result against the corresponding
check (.chk) file.  It emits a TAP report.

There are options for other useful behaviors; do "singletest -h" or
read the source code.

=== singlelift

The "singlelift" script normally takes the stem of a .svn file name,
captures stdout and stderr, converts the result tio Git fast-import
stream, and diffs the result against the corresponding check (.chk)
file. It emits a TAP report.

There are options for other behaviors; do "singlelift -h" or read
the source code.

=== liftcheck

By default, the "liftcheck" script takes a Subversion stream file, builds a Git
repository from it, and checks for differences using repotool's
compare-all function (all tags and branches). It emits a TAP report.

There are options to modify comparison and reporting behaviors; do
"liftcheck -h" or read the source code.

=== tapview

Digests TAP14 reports into a convenient summary form.

=== tapdiffer

Compares standard input with a check file and turns the diff into a
TAP report.  If the diff is nonempty it is shipped after the TAP
"not OK" as a details message.

=== delver

Run delve, the Golang symbolic debugger, on reposurgeon. The wrapper
is required to work around the problem that a program running under
an ordinary delver instance loses access to stdin.

== The tests

Keeping live Subversion repos under version control doesn't work very well; 
in particular, things like the entries file change too often.  So what we 
do is keep Subversion dump files and rebuild the repo before each test.

In general, a file named foo.chk is the expected output from a test involving
either some operation test on an input stream in foo.fi or a repo conversion
from foo.svn.

To see summary lines from all tests, 'make testlist'.  

The Subversion dumpfiles have summary comments in them that abuse a loophole
in Subversion's parser - header lines that begin with whitespace are ignored.
When you create a new one, insert a second line that begins with a space and
two pound signs.

=== Notes about making new Subversion test loads

It's good practice to write generators using the shell functions in
common-setup.sh.  Theye are easier to read and modify than the
stream files they generate.

1. To clone an existing test load foo.svn into the test repo,
'svn-to-svn -n <foo.svn'

2. To copy trunk, creating a tag named 'foo'

   svn copy file://${PWD}/test-repo/trunk file://${PWD}/test-repo/tags/foo

3. To delete a branch foo

   svn delete file://${PWD}/test-repo/branches/foo

== The agito test case

Samuel Howard had this to say:

git-svn's handling of tags is broken.

In this demonstration repository, a trunk directory of /trunk/proj exists,
containing some code.  This is improperly tagged by doing:

	svn cp trunk tags/proj-1.0

Where as what should have been done is this:

	svn cp trunk/proj tags/proj-1.0

This is significant because this is exactly what the CVS to SVN conversion
script (cvs2svn) does, to handle the fact that a CVS repository can contain
multiple modules.  Fixing a "mistake" like this is therefore necessary when
converting to SVN, to get tags stored properly.

In the SVN repository, this is fixed by deleting the branch and recreating
it properly (ie. the second command above).  To verify that this has been
done successfully, try this:

	svn log file://$PWD/myrepo/tags/proj-1.0

outputs:

	-----------------------------------------------------------------------
	r4 | fraggle | 2009-10-02 23:37:42 +0100 (Fri, 02 Oct 2009) | 2 lines

	Recreating the tag properly.

	-----------------------------------------------------------------------
	r1 | fraggle | 2009-10-02 23:36:41 +0100 (Fri, 02 Oct 2009) | 2 lines

	Initial import.

	-----------------------------------------------------------------------

Only the history of the directory being tagged and the commit that created the
tag are shown.  The "mistake" is kept in the history of /tags, but not in
the history of the tag itself.

The repository is then converted to git, using git-svn (see the shell script).
Two tags are created (proj-1.0@1 is the older, broken tag).  However, the
newer tag retains the history of the broken tag:

	git log tags/proj-1.0

outputs:

	Author: fraggle <fraggle@f01c4a58-e860-4891-ae86-76464917f484>
	Date:   Fri Oct 2 22:37:42 2009 +0000

	    Recreating the tag properly.

	commit 4aeb0a415e5be12d28a8af1128315e44d44a10d7
	Author: fraggle <fraggle@f01c4a58-e860-4891-ae86-76464917f484>
	Date:   Fri Oct 2 22:37:07 2009 +0000

	    Creating a tag in a BROKEN way, like how cvs2svn does it.

	commit 866f94c91de7628d7251098efcc133e6b5900f88
	Author: fraggle <fraggle@f01c4a58-e860-4891-ae86-76464917f484>
	Date:   Fri Oct 2 22:36:41 2009 +0000

	    Initial import.

	commit e8a2ee18774e319d33cb5bd418e03a5281b75268
	Author: fraggle <fraggle@f01c4a58-e860-4891-ae86-76464917f484>
	Date:   Fri Oct 2 22:36:41 2009 +0000

	    Initial import.

We now handle this case properly by detecting and ignoring the prior creation of
the tag. This produces a version of the history that is correct when
viewed from the head revision, but may not reproduce exactly the
states of tagged releases at all times past.

== The tagretract test case

According to Mike Fleetwood, fleetwood.svn was created with the following
sequence of operations:

------------------------------------------------------
svn commit -m 'commit one'
svn copy $REPO/trunk $REPO/tags/1.0 -m 'Release 1.0'
svn mv $REPO/tags/1.0 $REPO/tags/1.0rc1 -m 'No release ready yet'
svn commit -m 'commit two'
svn copy $REPO/trunk $REPO/tags/1.0 -m 'Fixed release 1.0'
------------------------------------------------------

He then converted it with these commands (note that branchify_map no
longer exists):

------------------------------------------------------
branchify_map :tags/(.*)/:tags/\1:
read </tmp/repo.svndump
prefer git
write >/tmp/repo.fi
------------------------------------------------------

This sequence is captured in tagretract.tst.

Before the simplification of permission calculation:
After conversion the tag named '1.0' referred to the first commit with
the first tagging message 'Release 1.0', rather than the second commit
with the second tagging message 'Fixed release 1.0'.

== A note about nut.svn

This was produced from the NUT Subversion repo.  Later it was stripped
and renumbered.  Later still, a 0 revision and an 89 revision were
added to make the revision sequence 0-origin and continuous, which the
Go implementation required at the time (this restriction has since
been removed).  Eventually it was truncated from 373 to 66 revisions
to speed up testing; most of the interesting pathologies are
concentrated in that leading segment.

It's too complex for correctness to be audited in detail by eyeball,
but it makes a good stability test. Any change that breaks the
Subversion analyzer even subtly is likely to produce a diff on this
test.

== The branchcreateempty test

This demonstrates what happens when a Subversion branch is created
as an empty directory and filled in with file copies in later revisions.

This sequence of options ought to be turned into a branch copy, but
every attempt to do so has created more problems than it solved.

== Generated ignore tests

ignoregen.sh can be used to regenerate the ignore.svn and
global-ignores.svn stream files by running generated sequences of
Subversion commands. Besides documernting the semantics of the
stream better than the stream itself does, this is a canary in
case the Subversion dump format ever changes incompatibly.

== Troubleshooting incorrect conversions

There is at present no known case of a valid Subversion stream file that
reposurgeon fails to convert in a version that can be verified correct.
In the past, such bugs have pretty much always to do with odd combinations of
branch-copy operations.  It is a safe bet that if there are future
bugs they will be in that context.

If you encounter such a bug, start by reading this:

https://svn.apache.org/repos/asf/subversion/trunk/notes/dump-load-format.txt

Then read the section on working with Subversion in the manual.

Then read a simple dumpfile - like, say, samplebranch.svn - to see how
dump streams look in practice. Next run

-----------------------------------------------------------
$ repocutter -q see <samplebranch.svn
-----------------------------------------------------------

for a condensed version of the structure that leaves out the blobs.
The "M-N" at the left margin expands to "Revision M, node N"; copy 
is just add with a copy source.

You can use liftcheck to see exactly how a conversion goes wrong;
you'll get a diff. By default liftcheck examines the head revision;
with the -r option you can check correctness at a specified 
esrtlier one.

You can use singlelift -o to dump a fast import stream made
from a named Subversion dump.  In this more you can also use
-l to set reposurgeon log flags.

== Tuning for speed

In the early 4.x releases reposurgeon achieved feature-completeness
and correctness.  New version-control systems should be supported by
writing front ends analogous to cvs-fast-export; the main things left
to do to reposugeon itself are to speed it up and reduce its working
set, so it will handle very large repostories more gracefully.

The most important single operations to speed up are fast-import
stream reads and Subversion dump stream reads.  These tend to
dominate processing time.

Do not hesitate to buy shorter running time with a larger working set;
conversely, we will resist changes that economize on memory usage but
cost cycles. Following the end of Dennard scaling we can expect RAM
costs to fall much faster than processor speeds rise; we want to be
on the good side of those cost gradients.

First thing to do when tuning is to make a test load.  The reposurgeon
history itself is large enough to be a useful one.  So:

  $ reposurgeon "read ." "write >rs.fi"

The ability to dump profile data is built into reposurgeon itself:

  $ reposurgeon "verbose 1" "profile start all reposurgeon" "read <rs.fi"

Once you have the profile data you can sic the profile viewer on it.
Have graphviz installed and do

  $ go tool pprof -http=":" ./reposurgeon reposurgeon.cpu.prof

There are lots of ways to explore the data but the single most
interesting one to start with is the graph view. The size of each box
is proportional to the number of profiler samples it appears in, and
the arrows are sized in proportion to the time spent calling them.
The 'top' view gives you the same data in tabular form:

     Flat  Flat%    Sum%      Cum    Cum%  Name
  203.36s  9.51%   9.51%  224.91s  10.52%  runtime.findObject
  132.43s  6.20%  15.71%  197.87s   9.26%  syscall.Syscall
   99.48s  4.65%  20.36%  107.34s   5.02%  syscall.Syscall6
   93.39s  4.37%  24.73%  395.22s  18.49%  runtime.mapassign_faststr
   84.39s  3.95%  28.68%  346.39s  16.20%  runtime.scanobject

This is telling us that (a) disk I/O (syscall.Syscall,
syscall.Syscall6) is slow, (b) assigning things to maps is a little
slower still (runtiem.mapassign_faststr), and (c) that garbage
collection is worse (runtime.scanobject, runtime.findObject).

The relative balance of these things does depend a lot on your
hardware. Most of the syscalls are for reading or writing files, so if
your disks are slower then that will be higher in the list. Reading
and/or writing less data would help (though it might be
impractical). Exercising the allocator less will be (and has been) a
good source of improvements. In a way these are good news - it
suggests we don't have a big-O/algorithmic problem. On the other hand,
it could just mean that they will only show up on larger repositories.

The obvious thing to do first is a search-and-destroy for heap escapes.
We can't avoid doing a lot of allocation; what we can do is avoid creating
lots of short-lived heap objects that will churn heap storage and trigger GC.

You can view the allocation profile with this command:

  $ go tool pprof -http=":" -sample_index=alloc_space ./reposurgeon reposurgeon.cpu.prof

This shows all allocations over the entire run of the program, not
just what was still live at a particular point in time. Using the
option -sample_index=alloc_space instead will show the count of all
objects allocated instead of the space that they occupied.

Finally, a trace of the execution is also recorded. This tracks which
threads are started, and which goroutines are running on them, at a
very high resolution. This trace is particularly useful for those
parts of Reposurgeon which are parallelized, as it is possible to see
where cpus are left idle. View the trace with this command:

  $ go tool trace reposurgeon.trace.prof

It will automatically open a page in your default web browser, but
unfortunately the trace viewer itself only works in Chrome or
Chromium; you'll need to open it there yourself if you prefer a
different browser.

In addition to the trace, this also provides a list of tasks, regions,
and associated log messages. Reposurgeon does not use this logging
capability very extensively, but it is used enough that you can see a
timeline of what Reposurgeon was doing:

  When                 Elapsed  Goroutine ID  Events
  0.000000000s  1m7.920970625s                Task 1 (incomplete)
  0.000125812      .                       1  region logfile started (duration: 15.964µs)
  0.000220496      .    94684              1  region readlimit started (duration: 3.431µs)
  0.000239855      .    19359              1  region set started (duration: 4.551µs)
  0.000281811      .    41956              1  region script started (duration: 260.3µs)
  0.000425845      .   144034              1  region branchify started (duration: 11.982µs)
  0.000472494      .    46649              1  region branchmap started (duration: 48.515µs)
  0.000557453      .    84959              1  region read started (duration: 33.919414851s)
  33.958593745   33.958036292              1  region authors started (duration: 3.646869ms)

Reposurgeon surrounds each command executed by the user with a region,
and each region adds a log entry; the duration of the region is also
calculated. The 'elapsed' column shows the time in nanoseconds that has
elapsed since the previous log message. These regions can be nested,
although this is not shown very clearly. In particular, the 'script'
regions will contain regions of all the commands that were in the
script that was run.

It may be useful to add additional logging of this type. The Go trace
library is used to add new regions to the trace file. Its first
argument is a Context object from the Go context library, which needs
to be passed down the call tree. The Context objects can have metadata
associated with them which is supposed to show up in the trace viewer,
but this feature is not yet exploited.

== Missing tests

FIXME: R and C handling in expunge needs tests

FIXME: Need test for repocutter filecopy with -f, and skipcopy.

FIXME: Meeds tests of bk, darcs, mtn.

== Some references

https://testanything.org/

https://blog.golang.org/profiling-go-programs

https://artem.krylysov.com/blog/2017/03/13/profiling-and-optimizing-go-web-applications/

https://github.com/google/pprof/blob/master/doc/README.md

https://www.signalfx.com/blog/a-pattern-for-optimizing-go-2/

http://www.agardner.me/golang/garbage/collection/gc/escape/analysis/2015/10/18/go-escape-analysis.html

https://github.com/golang/go/wiki/Performance

https://groups.google.com/forum/#!msg/golang-nuts/pxfhKGqHNv0/If4Gz09r_2gJ

// end