cheshrkat / git-webkit2png

git-webkit2png(1)

NAME

git-webkit2png - Generate visual diffs for git revisions.

SYNOPSIS

[verse] 'git webkit2png' [clean [-a | --all]]| run | | [help|-h]]

DESCRIPTION

git-webkit2png iterates over a list of URLs, generating a PNG for each URL by invoking webkit2png. The list of URLs to screenshot gets generated by a user-supplied program. Screenshots are stored per git revision and should a screenshot for a git revision already exist for a given URL, the existing screenshot is accepted as authoritative and not re-generated. This results in speedy diffs between already 'touched' revisions. Diffs are stored in a similar manner (if you have done the same diff before, it should load near-instantly).

Basic webkit2png

Suppose that you are on master and would like to generate screenshots
for a bunch of test pages.  Before we begin, webkit2png.urlsCommand must
be set to some value that when interpreted by the shell, will yield a
list of URLs to sreenshot.  For the sake of this example, let us assume
that webkit2png.urlsCommand is

---------------------
echo http://localhost
---------------------

Running

----------------
$ git webkit2png
----------------

a screenshot of this URL will be stored and webkit2png.post will be
invoked with the screenshot directory as the working directory.  It is
therefore handy to set webkit2png.post to something that is good for
navigating a bunch of screenshots.

wekit2png with a revision

By giving webkit2png a git reference, git webkit2png will be run twice: once on the checked-out branch and again on the given revision. After this is done, visual diffs will be generated between screenshots of corresponding URLs.

---

$ git webkit2png

Clearing stored screenshots

Because git-webkit2png relies heavily on already generated screenshots,
it often can be helpful to clear out these generated screenshots.  To
clear out the screenshots for the checked-out branch, simply

----------------------
$ git webkit2png clear
----------------------

Getting help
~~~~~~~~~~~~

Use `git webkit2png` to get a short usage description, and `git
webkit2png help` or `git bisect -h` to get a long usage description.

------------------
Step By Step Guide
------------------

`$ git clone [email protected]:tomgilligan/git-webkit2png.git`

`$ cd git-webkit2png/`

`$ make install`

`$ brew install imagemagick webkit2png parallel`

if on El Capitan, do https://github.com/paulhammond/webkit2png/issues/90

Add configuration to `<gitrepository>/.git/config`

	[webkit2png]
		# bash list of URLs - can be generated
		# urlsCommand = (bash list of URLs)
		# urlsCommand = echo ("http://example.com/1" "http://example.com/2")
		urlsCommand = "for i in $(ls $(git rev-parse --show-toplevel)/source/tests/|cut -f1 -d\".\"|grep -v \"^_\"); do echo \"http://localhost:8135/tests/$i.html\"; done"
		# post command (run when done)
		post = open .
		# You can restrict screenshots to a parent element in each URL
		selector = "#content"

Run up your dev server if working locally; your machine needs to be able to access the URLs.

`$ git webkit2png`

When done... go to `/webkit2png/000000..111111/` for screenshots of the current version

Run with any git hash or reference to generate further screenshots:

`$ webkit2png HEAD@{1.week.ago}`

When the second pass is done, there will be three directories: the first hash, the second, and a directory containing the diffs between the two.

Further runs will add more sets of screenshots and diffs.