
Kyle Dumont
View Altium circuits in your browser with GitHub
Overview
GitHub and Gitlab are becoming popular revision control tools, but did you know you can use them to render your circuit designs in the browser? This can be extremely helpful for quickly browsing through revisions or sharing your designs with people that might not have otherwise necessary software installed.
In this article we will:
Install AllSpice render tool
Set up a pre-commit hook to generate visible svgs

AllSpice render tool
The first step in this process step is to download and install AllSpice Diff and Render Tool. We'll use this to generate a vector image for each schematic file that GitHub can render.
After installing, you should see the following:

We're not going to use the GUI for this, so you can exit the application.
Setting up a pre-commit git hook
The next step is setting up a pre-commit git hook that will call AllSpice to render CLI, generate svgs, and add them to the project repo each time you commit changes to your Altium project.
By default, git will look for hooks in your `.git/hooks/` directory, which is not committed to the repo. However, I recommend creating a new location for this hook and adding it to the repository so that you can ensure everyone who commits to the project in the future will create an up-to-date rendering for your schematics.
Create a folder in your base repo called `.githooks` and add it to git with:
git config core.hooksPath .githooks
Note: this configures the git hook for your local repository. You will need to run this command for each git repo you want to enable the hook in. Best practice is to add this command to a README file.
Now we can add the pre-commit hook. The file needs to be named `pre-commit`.
The full pre-commit hook and example directory can be found here.
You can download the raw file above, place into the directory we created, and add it to the git repo. For example, using:
git add .githooks/pre-commit
However, if you're interested in understanding what's going on behind the scenes, I'll explain how it works below.
Finally, commit the git hook file to your repository with:
git commit -m "Add git hook to render schematics"
And you should see an svg rendered and added for each schematic in your repository.

The result
After pushing the file to your remote you'll find a viewable rendering for your product CAD data.

Demo: https://github.com/AllSpiceIO/Archimajor
💡 This pairs very well with File Icon for GitHub and GitLab Chrome extension.
What's next?
Next, we'll utilize the design renderings to recommend best-practices for conducting a design review or pull request in GitHub.

[Bonus] Understanding the git hook script
The first half of the githook resolves the install path for the AllSpice render tool.
#!/bin/sh
#
# Runs before commit message is added
# Exit non-zero to abort commit
# bypass with git commit --no-verify
# Needs executable permissions
# No arguments are passed to pre-commit
# Locate AllSpice
unameOut="$(uname -s)"
case "${unameOut}" in
Linux*) machine=Linux;;
Darwin*) machine=Mac;;
CYGWIN*) machine=Cygwin;;
MINGW*) machine=MinGw;;
MSYS*) machine=Win;;
*) machine="UNKNOWN:${unameOut}"
esac
if [ ${machine} == Win ] || [ ${machine} == MinGw ] || [ ${machine} == Cygwin ]; then ALLSPICE=~/AppData/Local/Programs/allspice/resources/utils/allspice.dist/allspice
elif [ ${machine} == Mac ] || [ ${machine} == Linux ]; then
ALLSPICE=/Applications/allspice/MacOS/allspice/resources/utils/allspice.dist/allspice
else
echo "Unsupported machine ${machine}"; exit 1
fi
Next, there is a special case for the first commit, which needs to diff against an empty object.
# Handle initial commit: diff against an empty tree object
if git rev-parse --verify HEAD >/dev/null 2>&1; then
against=HEAD
else
against=$(git hash-object -t tree /dev/null)
fi
We then build an array for the modified schematics, as well as the entire list of schematics in the repository.
modifiedSchematics=$(git diff --cached --diff-filter=M --name-only $against | grep -i \**.schdoc$)
allSchematics=$(git ls-files --cached | grep -i \**.schdoc$)
Finally, we traverse the modified array to generate new svgs using the AllSpice CLI
and the entire array list to generate an svg for any new schematics.
# Render each modified schematic file
for f in $modifiedSchematics; do
outfile="${f%.*}"
echo "Generating ${outfile}.svg"
"${ALLSPICE}" convert --svg --no-json --output "$outfile" "$f"
git add --force "${outfile}.svg"
done
# Render each schematic file that does not have an svg
for f in $allSchematics; do
outfile="${f%.*}"
if [ ! -f "${outfile}.svg" ]; then
echo "Generating ${outfile}.svg"
"${ALLSPICE}" convert --svg --no-json --output "$outfile" "$f"
git add --force "${outfile}.svg"
fi
done
If you'd like to see anything else or have any issues, feel free to reach out at info@allspice.io
Curious about some of the other ways AllSpice can improve your hardware development? Let us know below so we can tackle them in a future post, or send us an email at info@allspice.io.


Kyle is an experienced electrical engineer with 10 years of experience launching mass-production consumer products. He holds a B.S. in Electrical Engineering from Northeastern and an M.S. in Engineering and an MBA from Harvard. Driven by his passion for innovation in hardware development and his big-picture mindset, Kyle co-founded AllSpice in 2020.