#+TITLE: FreeCAD and Git
#+DATE: 2021-04-11T12:53:48-04:00
#+DRAFT: false
#+DESCRIPTION: How to efficiently version control FreeCAD files using git
#+TAGS[]: git freecad
#+KEYWORDS[]: git freecad
#+ALIASES[]: /posts/wip-freecad-and-git/
#+SLUG:
#+SUMMARY:

I've been working a lot with [[https://freecadweb.org/][FreeCAD]] since I got my 3D printer. It's
been a mostly excellent experience, but I've run a couple issues.

Between the MacOS and Linux version of FreeCAD (both 0.19, maybe
different builds?), and transferring files between machines using
Nextcloud, a project that I'd been working on for a couple days became
broken to the point where I could no longer modify the sketches,
rendering it useless.

This has led me to find out how I can manage these files through
version control like [[https://git-scm.com/][=git=]].

It would seem that FreeCAD files are nothing more than zip files
containing text documents, which should make this rather easy.

Unfortunately there isn't a standard process to git control a
zipped folder, though I have come across a couple methods which
when used together, result in an adequate solution.

The main component of this workaround is a great little script called
[[https://bitbucket.org/sippey/zippey/src/master/][zippey]], which allows git to efficiently store zip files using
something called a [[https://git-scm.com/docs/gitattributes#_filter][=filter= attribute]].

The second isn't as much a tool as it is a snippet from a [[https://tante.cc/2010/06/23/managing-zip-based-file-formats-in-git/][blog post]]
about diffing zip files using the [[https://git-scm.com/docs/gitattributes#_diff][=diff= attribute]]. By combining both
these methods we can arrive at a pretty good method of handling
FreeCAD save data.

The first step is to download the zippy python program. Since I
keep all source repositories under =~/src= in directories based on
the website and user who created them, I'll be cloning it to
=~/src/bitbucket.org/sippey/zippey=.

Then I configure my =~/.gitconfig= to so that the =diff= and =filter=
attribute settings are used globally. I'll also setup a global git
[[https://git-scm.com/book/en/v2/Customizing-Git-Git-Attributes][attributes]] file so that I don't need to set the association with
=.FCStd= files in each repo individually.

I add the following lines to my =~/.gitconfig=.

#+begin_src conf
[diff "zip"]
textconv = unzip -c -a
[core]
    attributesfile = ~/.gitattributes
[filter "zippey"]
    smudge = /home/dante/src/bitbucket.org/sippey/zippey/zippey.py d
    clean = /home/dante/src/bitbucket.org/sippey/zippey/zippey.py e
#+end_src

Then I create a =~/.gitattributes= file with the following content.

#+begin_src conf
*.FCStd filter=zippey
*.FCStd diff=zip
#+end_src

With this, =git= should be now be able to effectively diff and store
proper deltas when FreeCAD files are modified.

Keep in mind you need to redo this process on each computer you
plan on using this with, otherwise the files git produces won't
make any sense.