From ae75d413e05af84ec263ba1abba8d6b43481f139 Mon Sep 17 00:00:00 2001
From: Sebastian Holmin <sebastian.holmin@mullvad.net>
Date: Fri, 3 May 2024 10:51:45 +0200
Subject: [PATCH] Add comments explaining the files we are tracking

Also add a note on the `.git/packed-refs` file and
why we don't need to track it.
---
 mullvad-version/build.rs | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/mullvad-version/build.rs b/mullvad-version/build.rs
index 6b923253e3ee..8887ea5a214f 100644
--- a/mullvad-version/build.rs
+++ b/mullvad-version/build.rs
@@ -99,14 +99,17 @@ fn get_dev_suffix(release_tag: &str) -> Option<String> {
 fn rerun_if_git_ref_changed(release_tag: &str) -> std::io::Result<()> {
     let git_dir = Path::new("..").join(".git");
 
-    // If we build our output on information about HEAD we need to re-run if HEAD moves
+    // The `.git/HEAD` file contains the position of the current head. If in 'detached HEAD' state,
+    // this will be the ref of the current commit. If on a branch it will just point to it, e.g.
+    // `ref: refs/heads/main`. Tracking changes to this file will tell us if we change branch, or
+    // modify the current detached HEAD state (e.g. committing or rebasing).
     let head_path = git_dir.join("HEAD");
     if head_path.exists() {
         println!("cargo:rerun-if-changed={}", head_path.display());
     }
 
-    // If we build our output on information about the ref of the current branch, we need to re-run
-    // on changes to it
+    // The above check will not cause a rebuild when modifying commits on a currently checked out
+    // branch. To catch this, we need to track the `.git/refs/heads/$current_branch` file.
     let output = Command::new("git")
         .arg("branch")
         .arg("--show-current")
@@ -133,7 +136,15 @@ fn rerun_if_git_ref_changed(release_tag: &str) -> std::io::Result<()> {
     if git_release_tag_ref.exists() {
         println!("cargo:rerun-if-changed={}", git_release_tag_ref.display());
     };
-    Some(())
+
+    // NOTE: As the repository has gotten quite large, you may find the contents of the
+    // `.git/refs/heads` and `.git/refs/tags` empty. This happens because `git pack-refs` compresses
+    // and moves the information into the `.git/packed-refs` file to save storage. We do not have to
+    // track this file, however, as any changes to the current branch, 'detached HEAD' state
+    // or tags will update the corresponding `.git/refs` file we are tracking, even if it had
+    // previously been pruned.
+
+    Ok(())
 }
 
 /// Returns the commit hash for the commit that `git_ref` is pointing to.