Georg Lukas, 2025-05-05 14:34

This post documents how to convert a directory full of project release ZIP files into a git history with better diffs and commit dates. It was an itch I needed to scratch and there is no reason to keep the hacky tooling to myself.

The NX-KS project

I'm an active user of the NX-KS2 mod on my 2014 Samsung NX500 camera. The mod implements additional functionality and offers an UI overlay to access it. Under the hood, it's shell scripts and small UI helpers. The original developer KinoSeed vanished around 2017, and all official download locations are gone.

I've been carrying a few minor modifications in my $HOME and on my cameras since installing the mod, and I always wanted to properly track them in git. However, there was no original repository, and just using the last release 2.88 as the initial commit felt wrong to me.

Luckily, somebody collected the known releases and even added a README.html with a change log of sorts.

I want to convert that set of files into a git history now.

Preparing the inputs

I've downloaded all the ZIP files from NX-KS-mod/ and NX-KS-mod/archive/ into one common directory. To make the file names consistent, I had to rename the v2 files:

rename s/NX-KS2-/NX-KS-2./ nx-ks-mod-input/NX-KS2*

The change log in README.html contains the commit id of the ZIP file in the upstream project (yes, don't ask me!), the version string, a changelog, and a date.

I manually converted the README into tab-separated values as follows:

The full metadata table was saved to nx-ks-mod-changes.tsv.

The changes in 2.88 and 2.07 were undocumented, so I left them as "TODO" for the first iteration, checked the git diff after it, and improved the changelog on the second conversion re-run.

The 2.00m-repack version was based on the ZIP file name, I decided to keep it as-is in the commit history, but to manually change the git tag to v2.00m.

Converting the README

The project is providing a NX-KS_readme.odt (renamed to NX-KS2_readme.odt in the 2.x versions), which contains a description and sometimes can indicate changes. However, ODT is not a good format to git-diff (even though there are workarounds). As a hack, I'm using Pandoc to create a markdown approximation of the original document:

[ -f "NX-KS_readme.odt" ] && pandoc NX-KS_readme.odt -o NX-KS_readme.md
[ -f "NX-KS2_readme.odt" ] && pandoc NX-KS2_readme.odt -o NX-KS_readme.md

Unfortunately, the markup in the ODT is not using proper styles, so the result is far from perfect.

Creating the repository

We need to create an empty git repository first:

mkdir nx-ks-mod
cd nx-ks-mod
git init .

Committing the ZIP files

Then, for each ZIP file we have to perform the following steps:

1. Remove all previous content (in case a file was deleted):

    git rm -r .
   

2. Unpack the ZIP file (we are using find because we do not have a full file-name in our table):

     fn=$(find ../nx-ks-mod-input/ -name *$version.zip)
     unzip "$fn"
   

3. Pandoc the README (see above)

4. Commit everything, back-dating to $date and cheating the file name into the committer id (it could be added into the commit message as well), then tagging it with the version from the table:

     git add .
     git commit --date="$date 00:00:00" \
                --author "$(basename $fn) <$email>" \
                -m "$changes"
     git tag "v$version"
   

The final script

There is one more thing. The order in the README was newest-first, but for a proper commit history, we need to reverse the order, which we do using tac.

The complete result is this:

#!/bin/bash

mkdir nx-ks-mod && (cd nx-ks-mod ; git init .)

tac nx-ks-mod-changes.tsv | \
while IFS=$'\t' read version changes date ; do
    echo "-- $date -- $version -- $changes --"
    echo ""
    fn=$(find nx-ks-mod-input/ -name *$version.zip)
    cd nx-ks-mod
    git rm -r .
    unzip "../$fn"
    [ -f "NX-KS_readme.odt" ] && pandoc NX-KS_readme.odt -o NX-KS_readme.md
    [ -f "NX-KS2_readme.odt" ] && pandoc NX-KS2_readme.odt -o NX-KS_readme.md
    git add .
    git commit --date="$date 00:00:00" --author "$(basename $fn) <georg@op-co.de>" -m "$changes"
    git tag "v$version"
    cd ..
    echo
done

Not perfect, but good enough to create a commit history, as can be seen on github/nx-ks-mod.

Discuss on Mastodon