eda-tools/schhist/README

schhist - Graphical revision history of schematics
==================================================

The schhist system walks the git revision history of a KiCad project
and produces Web-browseable graphical differences of the schematics.

It does so by checking out each revision from git, sanitizing the
project to prevent problems what would cause eeschema to stop and
display an error dialog, using eeschema to "plot" the project to
Postscript, making some small adjustments (position, line width) to
the Postscript, converting it to PPM with Ghostscript, making a
pixel-wise comparison of revisions, and arranging the resulting
images in an HTML page. Further more, sub-pages with magnifications
and PDF files are generated.


This work is distributed under the terms of the GNU GENERAL PUBLIC
LICENSE, Version 2:

  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

For your convenience, a copy of the complete license has been included
in the file COPYING.GPLv2.


schhist2web
-----------

Web-browseable graphical revision history of schematics 
...


subschname2file
---------------

Translate a subsheet's name to the sheet file's name
...


sanitize-profile
----------------

Remove items from a KiCad profile that may cause an upset
...


sanitize-schem
--------------

Remove items from KiCad schematics that may cause an upset
...


gitsch2ps
---------

Generate PS files for KiCad schematics in git
...


normalizeschps
--------------

Normalize eeschema Postscript
...


ppmdiff
-------

Mark differences in two PPM files
...


schps2pdf
---------

Generate PDF files from Eeschema Postscript 
...


schps2ppm
---------

Generate PPM files from normalized Eeschema Postscript
...


gitenealogy
-----------

Trace the ancestry of a file in git across renames
...


gitwhoareyounow
---------------

gitwhoareyounow is used to find a single identity for files that have been
renamed in the history of a project.

E.g., if a file foo.c is created in revision 1 (assuming successive revisions
numbered 1, 2, etc.) and renamed to bar.c in revision 2, gitwhoareyounow
would then return the name bar.c for this file in any revision we consider.

gitwhoareyounow has to be given a repository in which the historical commit
has been checked out, and the name the file had in that commit.

Example:

$ git init
$ date >foo.c
# git add foo.c
# git commit -m "foo.c, rev 1"
$ git mv foo.c bar.c
$ git commit -m "foo.c renamed to bar.c, rev 2"
$ git checkout HEAD~1
$ ls
foo.c
$ gitwhoareyounow . foo.c
bar.c


Multiple files may use the same identity
- - - - - - - - - - - - - - - - - - - - 

E.g., if a file foo.c is created in revision 1, deleted in revision 3, and
then a new file named foo.c is created in revision 4, gitwhoareyounow would
call both of them foo.c


Multiple files sharing the same identity can conflict
- - - - - - - - - - - - - - - - - - - - - - - - - - -

E.g., taking the first example with foo.c renamed to bar.c in revision 3, if
a file bar.c existed in revision 1 but was deleted in revision 2,
gitwhoareyounow running on revision 1 would identify both the foo.c and the
bar.c as bar.c

gitwhoareyounow does not try to resolve such conflicts. This is already
complex enough as it is :-)