forgejo: document ifcmerge mergeability — bare repo gitattributes finding

Investigation confirmed: Forgejo's git merge-tree --write-tree (git ≥2.38)
does invoke configured merge drivers for .ifc files.

Key finding: bare repositories do NOT read committed .gitattributes — the
merge driver is silently skipped without a system-wide core.attributesFile.

Changes:
- server-config/gitattributes: new file to deploy at /etc/gitattributes,
  containing "*.ifc merge=ifcmerge"
- server-config/gitconfig-ifcmerge: adds [core] attributesFile = /etc/gitattributes
  and explains the bare-repo constraint
- forgejo/README.md: rewrites ifcmerge section with investigation findings,
  deployment steps, and distinction between server-side vs client-side setup

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.beads/issues.jsonl

@@ -29,7 +29,7 @@
 {"id":"ifcurl-bqt","title":"Phase 4: Bonsai IFCDOCUMENTREFERENCE federation via ifc://","description":"When opening a model via ifc://, resolve IFCDOCUMENTREFERENCE locations using the repo and ref from the root file's URL as context. Resolve ifc:// locations in linked model references recursively. Requires the Phase 4 protocol handler (ifcurl-0oj).","status":"deferred","priority":3,"issue_type":"feature","owner":"bruno@postle.net","created_at":"2026-04-23T05:48:56Z","created_by":"Bruno Postle","updated_at":"2026-04-23T06:15:11Z","defer_until":"2026-12-01T00:00:00Z","dependencies":[{"issue_id":"ifcurl-bqt","depends_on_id":"ifcurl-0oj","type":"blocks","created_at":"2026-04-23T06:49:02Z","created_by":"Bruno Postle","metadata":"{}"}],"dependency_count":1,"dependent_count":1,"comment_count":0}
 {"id":"ifcurl-lcr","title":"Phase 4: Bonsai 'Copy view URL' button","description":"Add a button to Bonsai that generates an ifc:// URL from the current state: git remote/ref/file path, active selection as IfcOpenShell selector, current camera as camera+fov or scale params in IFC world coordinates, active clipping planes as clip params, current visibility mode. Default to commit hash ref; secondary option for @heads/ ref.","status":"deferred","priority":3,"issue_type":"feature","owner":"bruno@postle.net","created_at":"2026-04-23T05:48:55Z","created_by":"Bruno Postle","updated_at":"2026-04-23T06:15:10Z","defer_until":"2026-12-01T00:00:00Z","dependencies":[{"issue_id":"ifcurl-lcr","depends_on_id":"ifcurl-0oj","type":"blocks","created_at":"2026-04-23T06:49:01Z","created_by":"Bruno Postle","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
 {"id":"ifcurl-0oj","title":"Phase 4: Bonsai ifc:// OS protocol handler","description":"Register ifc:// as an OS protocol handler in Bonsai on installation (Windows, macOS, Linux). On receiving a URL, resolve the git source, load the model, and apply the view state from the URL parameters (camera, selector, clipping planes, visibility mode). This is the foundation for all other Phase 4 work.","status":"deferred","priority":3,"issue_type":"feature","owner":"bruno@postle.net","created_at":"2026-04-23T05:48:45Z","created_by":"Bruno Postle","updated_at":"2026-04-23T06:15:09Z","defer_until":"2026-12-01T00:00:00Z","dependency_count":0,"dependent_count":3,"comment_count":0}
-{"id":"ifcurl-cyw","title":"Phase 3c: Verify Forgejo merge-ability check works with ifcmerge","description":"Investigate whether Forgejo's merge-ability check (the 'branches can be merged automatically' indicator) correctly reflects ifcmerge's ability to handle .ifc files. Determine if Forgejo runs a trial git merge or uses a heuristic. If needed, patch Forgejo to run a trial git merge --no-commit to get an accurate result.","status":"open","priority":3,"issue_type":"task","owner":"bruno@postle.net","created_at":"2026-04-23T05:48:22Z","created_by":"Bruno Postle","updated_at":"2026-04-23T05:48:22Z","dependencies":[{"issue_id":"ifcurl-cyw","depends_on_id":"ifcurl-c69","type":"blocks","created_at":"2026-04-23T06:48:29Z","created_by":"Bruno Postle","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
+{"id":"ifcurl-cyw","title":"Phase 3c: Verify Forgejo merge-ability check works with ifcmerge","description":"Investigate whether Forgejo's merge-ability check (the 'branches can be merged automatically' indicator) correctly reflects ifcmerge's ability to handle .ifc files. Determine if Forgejo runs a trial git merge or uses a heuristic. If needed, patch Forgejo to run a trial git merge --no-commit to get an accurate result.","status":"closed","priority":3,"issue_type":"task","assignee":"Bruno Postle","owner":"bruno@postle.net","created_at":"2026-04-23T05:48:22Z","created_by":"Bruno Postle","updated_at":"2026-04-24T08:27:25Z","started_at":"2026-04-24T08:19:58Z","closed_at":"2026-04-24T08:27:25Z","close_reason":"Verified: git merge-tree --write-tree (Forgejo's code path for git ≥2.38) does invoke merge drivers. Bare repos require core.attributesFile in /etc/gitconfig — committed .gitattributes not read. Added gitattributes server-config file and updated deployment docs.","dependencies":[{"issue_id":"ifcurl-cyw","depends_on_id":"ifcurl-c69","type":"blocks","created_at":"2026-04-23T06:48:29Z","created_by":"Bruno Postle","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
 {"id":"ifcurl-c69","title":"Phase 3c: Register ifcmerge as git merge driver on Forgejo server","description":"Configure ifcmerge as the git merge driver for .ifc files on the Forgejo server. Add to /etc/gitconfig or ~forgejo/.gitconfig: [merge \"ifcmerge\"] name = IFC merge driver / driver = ifcmerge %O %A %B %L. Add *.ifc merge=ifcmerge to server-side gitattributes. This allows Forgejo's 'merge automatically' path to invoke ifcmerge via git when merging .ifc files.","status":"closed","priority":3,"issue_type":"task","owner":"bruno@postle.net","created_at":"2026-04-23T05:48:21Z","created_by":"Bruno Postle","updated_at":"2026-04-24T08:15:20Z","closed_at":"2026-04-24T08:15:20Z","close_reason":"Documented ifcmerge driver registration (gitconfig-ifcmerge), gitattributes setup, merge direction constraint, and merge-commit strategy requirement","comments":[{"id":"019dbc54-bf0a-76e2-b64d-7d1681f0c730","issue_id":"ifcurl-c69","author":"Bruno Postle","text":"ifcmerge needs to be installed as a pair of merge tools because the merge process is asymmetrical and we need to be able to prefer one branch over another (because step-ids from one branch get rewritten in the merged file). In practice we prefer origin and/or main/master branches. there is code in the ifcopenshell bonsai ifcgit module for reference.","created_at":"2026-04-23T21:52:44Z"}],"dependency_count":0,"dependent_count":1,"comment_count":1}
 {"id":"ifcurl-8ns","title":"Future: Contribute ifc:// URL parsing to IfcOpenShell","description":"Once the Python core URL parsing and resolution logic is stable, contribute it to IfcOpenShell as a shared utility. Not a prerequisite for any phase — pursue after Phase 1 has been stable in production use for a while.","status":"open","priority":4,"issue_type":"task","owner":"bruno@postle.net","created_at":"2026-04-23T05:49:33Z","created_by":"Bruno Postle","updated_at":"2026-04-23T05:49:33Z","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"id":"ifcurl-9yr","title":"Future: BCF export endpoint /bcf","description":"Add a /bcf endpoint to the preview service: POST /bcf with body {url: 'ifc://...'} returns a BCF zip file. Resolve the selector to a GUID set and construct a BCF viewpoint from the camera, clipping planes, and visibility state. Not planned before Phase 2 is complete.","status":"open","priority":4,"issue_type":"feature","owner":"bruno@postle.net","created_at":"2026-04-23T05:49:25Z","created_by":"Bruno Postle","updated_at":"2026-04-23T05:49:25Z","dependency_count":0,"dependent_count":0,"comment_count":0}

forgejo/README.md

@@ -27,7 +27,8 @@ forgejo/
     footer.tmpl                         ← "View in 3D" button injection
   server-config/
     ifcurl-preview.service              ← systemd unit for the preview service
-    gitconfig-ifcmerge                  ← git merge driver config for .ifc files
+    gitconfig-ifcmerge                  ← git merge driver registration for /etc/gitconfig
+    gitattributes                       ← system-wide gitattributes for bare repos
 ```
 
 ---
@@ -188,6 +189,18 @@ no preview image.
 Configuring `ifcmerge` as the git merge driver for `.ifc` files lets Forgejo
 automatically merge IFC pull requests instead of marking them as conflicted.
 
+### How Forgejo checks mergeability
+
+Forgejo (with git ≥ 2.38) uses `git merge-tree --write-tree` to perform a
+trial merge in the bare repository.  This command **does** invoke configured
+merge drivers — confirmed by testing.  With ifcmerge set up correctly,
+the "can be automatically merged" indicator on a PR reflects ifcmerge's
+actual result, not a naive text-conflict check.
+
+**Important:** bare repositories do not read committed `.gitattributes` files
+from the tree.  The merge driver must be declared via a system-wide
+`core.attributesFile` setting in `/etc/gitconfig`.
+
 ### Prerequisites
 
 `ifcmerge` is a single Perl script from
@@ -206,37 +219,23 @@ Verify it is on `PATH` for the `forgejo` system user:
 sudo -u forgejo which ifcmerge
 ```
 
-### Register the merge drivers
+### Deploy the config files
-
-Append `server-config/gitconfig-ifcmerge` to the server's global git config:
 
 ```bash
-sudo git config --system --add include.path /path/to/forgejo/server-config/gitconfig-ifcmerge
+# System-wide gitattributes (the critical piece for bare repos)
+sudo cp forgejo/server-config/gitattributes /etc/gitattributes
+
+# Append merge driver registration + core.attributesFile to /etc/gitconfig
+sudo git config --system include.path /path/to/ifcurl/forgejo/server-config/gitconfig-ifcmerge
 ```
 
-Or copy the two `[merge "…"]` blocks directly into `/etc/gitconfig`.
+Or apply the blocks from `server-config/gitconfig-ifcmerge` directly into
-
+`/etc/gitconfig` by hand.
-### Set the per-repository gitattributes
-
-Add a `.gitattributes` file to each IFC repository:
-
-```
-*.ifc merge=ifcmerge
-```
-
-Or set a server-wide default by adding to
-`/usr/share/git-core/templates/info/attributes` (applied to all newly
-initialised repos):
-
-```
-*.ifc merge=ifcmerge
-```
 
 ### Merge direction
 
 The merge driver is asymmetrical: `ifcmerge` rewrites STEP IDs from `%B`
-(theirs) to match `%A` (ours), so `%A`'s ID space is preserved in the
+(theirs) to match `%A` (ours), so `%A`'s ID space is preserved.
-merged file.
 
 For Forgejo, use the **"Merge commit"** strategy (not rebase or squash).
 With a merge commit, `%A` is always the base branch (e.g. `main`) and
@@ -244,9 +243,23 @@ With a merge commit, `%A` is always the base branch (e.g. `main`) and
 existing cross-references remain valid.
 
 A second driver `ifcmerge_ours` is defined in the config file for cases
-where the base branch arrives as `%B`; see the comments in
+where the base branch arrives as `%B`; see comments in
 `server-config/gitconfig-ifcmerge` for details.
 
+### Client-side `.gitattributes`
+
+For client-side merges (`git merge` on a developer's machine) committed
+`.gitattributes` files in the repository work fine.  It is still worth
+adding one:
+
+```
+*.ifc merge=ifcmerge
+```
+
+This ensures developers with ifcmerge installed get automatic IFC merges
+locally, and tools that read gitattributes (e.g. diff viewers) can
+identify `.ifc` files correctly.
+
 ---
 
 ## Upgrading Forgejo

forgejo/server-config/gitattributes

@@ -0,0 +1,12 @@
+# System-wide gitattributes for the Forgejo server.
+# Reference this file from /etc/gitconfig:
+#
+#   [core]
+#       attributesFile = /etc/gitattributes
+#
+# This causes git merge-tree --write-tree (used by Forgejo's mergeability
+# check) to invoke ifcmerge for .ifc files in bare repositories.
+# Committed per-repo .gitattributes files are NOT read by git in bare-repo
+# context and are therefore insufficient for the server-side conflict check.
+
+*.ifc merge=ifcmerge

forgejo/server-config/gitconfig-ifcmerge

@@ -1,14 +1,28 @@
-# Add to /etc/gitconfig (or ~forgejo/.gitconfig) on the Forgejo server.
+# Add to /etc/gitconfig on the Forgejo server.
 #
-# Two drivers are registered because the merge is asymmetrical — ifcmerge
+# IMPORTANT: also set core.attributesFile so that bare repositories pick up
-# rewrites STEP IDs from %B to match %A's ID space.  The base-branch must
+# the merge driver.  Committed per-repo .gitattributes files are NOT read by
-# always be %A so its IDs are preserved.
+# git merge-tree --write-tree in bare-repo context.
 #
-#   ifcmerge        — use when the base branch is %A (standard 'merge commit')
+#   [core]
-#   ifcmerge_ours   — use when the base branch is %B (rebase direction);
+#       attributesFile = /etc/gitattributes
-#                     swaps the roles so base-branch IDs are still preserved.
+#
-#                     Requires ifcmerge to support --prefer-other; if not,
+# and put "*.ifc merge=ifcmerge" in /etc/gitattributes (see gitattributes
-#                     use 'merge commit' strategy exclusively and omit this.
+# in this directory).
+#
+# How the merge drivers work
+# --------------------------
+# ifcmerge rewrites STEP IDs from %B to match %A's ID space, so %A's IDs
+# are preserved in the merged result.  Use the "Merge commit" strategy in
+# Forgejo so that %A is always the base branch (e.g. main).
+#
+# Two variants are registered for symmetry:
+#   ifcmerge        — base branch is %A (standard merge-commit direction)
+#   ifcmerge_ours   — base branch is %B (rebase direction); swaps %A/%B so
+#                     base-branch IDs are still preserved
+
+[core]
+    attributesFile = /etc/gitattributes
 
 [merge "ifcmerge"]
     name = IFC merge driver (base is ours)