Using Git to manage my reMarkable configuration

June 14, 2021 • Reading time: 5 minutes

Like what seems like most of the tech world by now, I recently got a reMarkable 2 tablet and love it. Major credit where it's due: reMarkable doesn't even make you jump through hoops to get root filesystem access. It's enabled right out of the box, and you just have to plug in a USB cable and connect using the IP address and password provided in the on-device help. No danger of tivoization here.

However, it does get tripped up slightly by the classic open-source foible of deciding that making an edge case feature theoretically possible is good enough, and there's no need to make it intuitive. In this case, I speak of modifying your lock screen and adding custom templates. Both workarounds involve manually modifying a particular directory on the device, /usr/share/remarkable, which gets overwritten every time you install a software update. Fortunately, Git has my back!

Basically, I want to ensure that my custom templates and whatnot never go away (or at least that I can get them back easily), while also respecting new changes coming in from the software updates. Fortunately, this is one of Git's reasons for existing!

To start with, I copy all of the files in that directory off of the reMarkable:

$ git init remarkable
Initialized empty Git repository in /home/mikkel/Projects/remarkable/.git/
$ cd remarkable
$ scp -r [email protected]:/usr/share/remarkable/* .
320_R259_AFAB21_ED103TC2M1_TC.wb 100%  276KB   5.8MB/s   00:00    
320_R292_AFBC21_ED103TC2M1_TC.wb 100%  278KB   7.1MB/s   00:00    
320_R299_AFC421_ED103TC2U2_VB330 100%  281KB   7.2MB/s   00:00    
...

This is my baseline, with all of the files in their pristine original state. I want a copy of this in case I mess something up, but also so that I can track future changes coming in from upstream. With that in mind, I'm not just going to commit these files and call it a day, I'm going to create a new branch just for them.

$ git checkout -b upstream
Switched to a new branch 'upstream'
$ git add .
$ git commit -m "Initial commit"
[upstream (root-commit) 25e54f9] Initial commit
 230 files changed, 21829 insertions(+)
 create mode 100644 320_R259_AFAB21_ED103TC2M1_TC.wbf
 create mode 100644 320_R292_AFBC21_ED103TC2M1_TC.wbf
 create mode 100644 320_R299_AFC421_ED103TC2U2_VB3300-KCD_TC.wbf
...

Righto. Now time to make my own changes. The blog posts linked above cover some things you can do by messing around in this directory, so I'm not going to get into that here.

$ git checkout -b main
Switched to a new branch 'main'

// (I make my changes)

$ git add .
$ git commit -m "Add some truly amazing templates"
[main 39d5723] Add some truly amazing templates
$ scp -r * [email protected]:/usr/share/remarkable
320_R259_AFAB21_ED103TC2M1_TC.wb 100%  276KB   3.1MB/s   00:00    
320_R292_AFBC21_ED103TC2M1_TC.wb 100%  278KB   3.0MB/s   00:00    
320_R299_AFC421_ED103TC2U2_VB330 100%  281KB   3.0MB/s   00:00    
...

I restart my reMarkable and everything is just fine.

Okay, now fast-forward a few weeks. A new reMarkable update is out, and as usual my /usr/share/remarkable directory has been overwritten. As always, I have no idea what it's been overwritten with - maybe just the same files, but maybe there's some super-important update or new template hidden in there. Time to use Git to find out!

$ git checkout upstream
Switched to branch 'upstream'
Your branch is up to date with 'origin/upstream'.
$ rm -r *
$ scp -r [email protected]:/usr/share/remarkable/* .
320_R259_AFAB21_ED103TC2M1_TC.wb 100%  276KB   5.8MB/s   00:00    
320_R292_AFBC21_ED103TC2M1_TC.wb 100%  278KB   7.1MB/s   00:00    
320_R299_AFC421_ED103TC2U2_VB330 100%  281KB   7.2MB/s   00:00    
...

// (I would use rsync instead of rm/scp, but reMarkable doesn't have it by default.)

$ git status
On branch upstream
Your branch is up to date with 'origin/upstream'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   update.conf

no changes added to commit (use "git add" and/or "git commit -a")
$ git diff
diff --git a/update.conf b/update.conf
index aabc7ea..2f81117 100644
--- a/update.conf
+++ b/update.conf
@@ -3,4 +3,4 @@
 #SERVER=https://get-updates.cloud.remarkable.engineering/service/update2
 #GROUP=Prod
 #PLATFORM=reMarkable2
-REMARKABLE_RELEASE_VERSION=2.7.0.51
+REMARKABLE_RELEASE_VERSION=2.7.1.53

Okay, this update isn't so exciting: just a release version change to a config file. But it's exciting that I can tell so easily that the update isn't exciting! I should still make sure to incorporate the unexciting changes before I copy my changes back to the device.

$ git commit -a -m "Update to version 2.7.1.53"
[upstream 102cd92] Update to version 2.7.1.53
 1 file changed, 1 insertion(+), 1 deletion(-)
$ git checkout main
Switched to branch 'main'
Your branch is up to date with 'origin/main'.
$ git merge upstream -m "Merge branch 'upstream' into main: 2.7.1.53"
Merge made by the 'recursive' strategy.
 update.conf | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

If I'd, say, invented my own version numbering scheme, Git would helpfully inform me of the fact at this point through a merge conflict. I haven't done that, so everything goes through with no problem at all. I can now copy the files from my repo back to the device, secure in the knowledge that I'm not overwriting any updates that might cause me problems in the future.

$ scp -r * [email protected]:/usr/share/remarkable
320_R259_AFAB21_ED103TC2M1_TC.wb 100%  276KB   3.1MB/s   00:00    
320_R292_AFBC21_ED103TC2M1_TC.wb 100%  278KB   3.0MB/s   00:00    
320_R299_AFC421_ED103TC2U2_VB330 100%  281KB   3.0MB/s   00:00    
...