xlgit 0.1.0__tar.gz

xlgit-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

xlgit-0.1.0/NOTICE

@@ -0,0 +1,5 @@
+xlgit
+Copyright 2026 Michael Fowler
+
+This product includes software developed by Michael Fowler
+(https://github.com/MichaelFowler1/excel-git).

xlgit-0.1.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: xlgit
+Version: 0.1.0
+Summary: Cell-level diff and merge for Excel workbooks in git, keeping charts, tables and pivots
+Author: Michael Fowler
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/MichaelFowler1/excel-git
+Project-URL: Issues, https://github.com/MichaelFowler1/excel-git/issues
+Keywords: excel,git,merge,diff,xlsx,spreadsheet,version-control
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: lxml>=4.9
+Dynamic: license-file
+
+# xlgit
+
+> Beta (0.1.0). Every release is fuzz-tested against thousands of real-world workbooks, but you'll still find cases it gets wrong. Git keeps every version, so a bad merge can always be undone. Please [open an issue](https://github.com/MichaelFowler1/excel-git/issues) when something looks wrong.
+
+Git and GitHub treat `.xlsx` as an opaque binary blob. You can commit, fork and branch it, but a diff just says "binary file changed" and any merge where both sides touched the file is a conflict. This fixes that.
+
+## What you get
+
+| | Without xlgit | With xlgit |
+|---|---|---|
+| `git diff` | `Binary files differ` | `changed Budget!B2 1000 -> 1100`, plus inserted, deleted and moved rows, and chart, image and comment changes |
+| Seeing changes | n/a | `xlgit diff --html`: the sheet as a grid in your browser, changes highlighted |
+| Merge, different cells edited | conflict, pick one whole file | merges cleanly |
+| Merge, one side inserted rows | conflict | the other side's edits follow their rows |
+| Merge, same cell edited | conflict | conflict on just that cell, listed in a `_merge_conflicts` sheet with a link to it |
+| Charts, images, comments, formatting, macros | n/a | kept, and their edits to them carried over |
+| Tables and pivot tables | n/a | merged: you add rows, they add a column, you get both |
+| Pull request on GitHub | "binary file not shown" | bot comment with a table of every changed cell, chart, table and pivot |
+
+Formulas are compared as formulas (`=B2+C2`), not their cached results.
+
+## Get started
+
+You need git. Then, once per computer, either:
+
+**With Python** (3.9 or newer):
+
+```bash
+pip install xlgit
+xlgit install
+```
+
+**Without Python:** download the program for your computer from the [latest release](https://github.com/MichaelFowler1/excel-git/releases/latest) (`xlgit-windows.exe`, `xlgit-macos-arm64` for Apple silicon, `xlgit-macos-intel`, `xlgit-linux`), rename it to `xlgit` (`xlgit.exe` on Windows), put it somewhere it will stay, and run `xlgit install`. On Windows you can also just double-click it and it offers to set itself up. The downloads aren't code-signed yet: on Windows click "More info" then "Run anyway"; on a Mac, right-click it, choose Open, then Open again. If you move the program later, run `xlgit install` again.
+
+That's it. Every git repository on this computer now understands `.xlsx` and `.xlsm` files, including ones you clone or create later. Keep using git the way you already do.
+
+To also get a comment listing the changed cells on every GitHub pull request, run this once inside the repository and push:
+
+```bash
+xlgit install --github
+```
+
+Run `xlgit` on its own at any time to see the commands and check that everything is set up.
+
+## Everyday use
+
+**See what changed.** `xlgit diff` lists every cell that changed in your workbooks since the last commit. Inserted, deleted and moved rows show up as rows, not as every cell below them changing. `git diff`, `git log -p` and `git show` show cell changes too.
+
+```
+$ xlgit diff
+=== budget.xlsx ===
+changed        Budget!C3  350 -> 999
+row inserted   Budget row 4  A: 'Gas', B: 60, C: 70, D: =B4+C4
+changed        Budget!D8  =SUM(D2:D6) -> =SUM(D2:D7)
+```
+
+`xlgit diff --html` opens the same changes in your browser, laid out like the spreadsheet:
+
+<img src="docs/visual-diff.png" alt="Visual diff: a changed cell shows its old value, an inserted row is green, a changed SUM range is highlighted" width="480">
+
+**Merge.** `git merge` and `git pull` combine edits from both branches cell by cell. If you changed different cells, there's nothing to do.
+
+**When both of you changed the same cell**, git stops and xlgit tells you which cells:
+
+```
+xlgit merged budget.xlsx: took 3 cell(s) from the other branch, but 1 change(s) clash.
+  Budget B2: yours 1100, theirs 1200 (was 1000)
+  Your values were kept. Every clash is listed, with a link, on the sheet '_merge_conflicts'.
+```
+
+Open the workbook, go through the `_merge_conflicts` sheet (each row links to its cell), fix the cells, delete that sheet, save, then run `git add budget.xlsx` and `git commit`. Git keeps every version, so nothing is ever lost: `git merge --abort` undoes the whole merge.
+
+## Found a problem?
+
+Please [open an issue](https://github.com/MichaelFowler1/excel-git/issues/new/choose). Bug reports on real workbooks are the most useful thing you can give this project, and you don't have to share your data to do it:
+
+```bash
+xlgit scrub --merge budget.xlsx     # during a merge that went wrong: base, yours, theirs, in one zip
+xlgit scrub old.xlsx new.xlsx       # any workbooks, e.g. for a wrong diff
+```
+
+`scrub` makes copies where every number, piece of text, comment, chart label and file property is replaced with made-up values, keeping formulas, layout, charts, tables and pivots, so the problem still shows up. Equal values stay equal across the files scrubbed together. Sheet names and named ranges are kept (formulas refer to them), macros are removed, and images are replaced with blank ones. Open the copies and check them before you share them.
+
+## How the merge works
+
+A workbook is a zip of XML files: one per sheet, one per chart, one per image and so on. Instead of re-saving the whole thing through a spreadsheet library (which is how charts used to get lost), xlgit starts from your copy's zip and only rewrites the XML that has to change:
+
+- **Cells**: 3-way merge cell by cell. A cell only one side changed takes that side's value.
+- **Rows**: if one branch inserted, deleted or moved rows and the other edited cells, the edits land on the rows where their cells ended up, with formula references renumbered the way Excel does it. An edit to a row the other branch deleted is a conflict.
+- **Charts, images, comments, macros**: 3-way merge object by object. If only their branch changed a chart, you get their version. If both did, yours is kept and it's flagged as a conflict. Chart edits caused by cell changes (Excel caches plotted values inside the chart) don't count as edits.
+- **Tables**: merged field by field. Their new column plus your new rows gives a table with both. Tables added on their branch come over, and if both branches added a `Table2`, theirs is renamed `Table3` and their formulas are updated to match.
+- **Pivot tables**: a pivot, its data cache and the cached records merge as one bundle. A branch that only refreshed a pivot (same layout, new data) doesn't count as an edit, so your data change and their "switch to Average" merge cleanly. New pivots from their branch come over, sharing an existing cache when they used one.
+- **Sheets**: new sheets on their branch come over whole, with their charts, tables and pivots. Renames and deletes merge too.
+- **Named ranges**: merged by name.
+
+Writers renumber a workbook's internal files on every save (add a chart to an early sheet and every later `chart1.xml` becomes `chart2.xml`). xlgit matches objects by what they are, like "the chart called Chart 1 on sheet Notes" or "table id 3", not by file name, so renumbering doesn't cause false conflicts.
+
+Excel recalculates every formula and refreshes affected pivot tables when it opens the merged file.
+
+## Commands
+
+```
+xlgit                        help, and whether everything is set up
+xlgit install                set up every repository on this computer (once)
+xlgit install --github       add pull request comments to this repository
+xlgit install --repo         set up only this repository
+xlgit uninstall [--repo]     undo the setup
+xlgit diff                   what changed in your workbooks since the last commit
+xlgit diff FILE              ... in one workbook
+xlgit diff OLD NEW           compare any two workbooks (--markdown for a table)
+xlgit diff --html [FILES]    open the changes in your browser (--out=page.html to save it)
+xlgit scrub FILE...          copies with every value made up, safe to attach to a bug report
+xlgit scrub --merge FILE     the three versions of a merge that went wrong, scrubbed, in one zip
+xlgit --version
+```
+
+Git runs `xlgit textconv` and `xlgit merge` itself; you don't need to.
+
+Don't want a package? `xlgit.py` is a single file. Copy it in, `pip install openpyxl lxml`, and run `python xlgit.py install`.
+
+### The GitHub Action
+
+`xlgit install --github` writes this workflow. You can also add it by hand:
+
+```yaml
+# .github/workflows/excel-diff.yml
+name: Excel diff
+on:
+  pull_request:
+    paths: ["**/*.xlsx", "**/*.xlsm"]
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  excel-diff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: MichaelFowler1/excel-git@v0.1.0
+```
+
+It keeps one comment per pull request up to date as you push. Pull requests from forks can't be commented on with GitHub's default token, so for those the changed cells go in the run's summary page instead.
+
+## Tests
+
+```bash
+pip install -r requirements-dev.txt
+python -m pytest tests
+```
+
+The tests build workbook versions with charts, comments and named ranges, run real `git merge` through the driver, and check every object survived. Set `XLGIT_KEEP=some/dir` to keep the merged files and open them in Excel yourself.
+
+### Fuzzing against real workbooks
+
+`fuzz/merge_fuzz.py` runs the merge over a folder of real spreadsheets. For each one it makes two branches with random cell edits, merges them, and checks the result: it opens, every edit from both sides is there with its exact type and value, nothing else changed, no chart, table or pivot was lost, and the conflicts reported are exactly the cells both sides changed.
+
+```bash
+pip install py7zr
+fuzz/fetch_corpus.sh corpus            # ~17,000 workbooks: Enron corpus + open-source test suites
+python fuzz/merge_fuzz.py corpus --keep failed/
+```
+
+`--keep` saves the base, ours, theirs and merged files of every failure. `--rounds N` tries N different random edits per workbook.
+
+## Limits
+
+- Formatting changes their branch made to existing cells come over only when both branches have the same set of styles. Otherwise your formatting is kept.
+- Column widths, merged cells and conditional formatting on existing sheets aren't merged. Yours are kept.
+- Until Excel refreshes a merged pivot, the numbers in its cells are the old ones. Excel does this on open, but tools that read the file without Excel (pandas, openpyxl) see the stale values.
+- Slicers, timelines and tables linked to external data connections aren't merged. They're reported as conflicts so nothing disappears silently.
+- If both branches added a chart to a sheet that had none, only yours is kept (flagged).
+- Inserted and deleted rows are followed when only one branch changed a sheet's rows. If both branches inserted or deleted rows on the same sheet, that sheet merges cell by cell, and cells that only moved can show up as conflicts.
+- Rows are recognised by their contents. A row change can't always be recognised (say, deleting one of many identical rows); then the sheet merges cell by cell and anything unclear is reported as a conflict, never guessed.
+- Inserted columns show as changed cells for now.
+- `.xls` (the old pre-2007 format) isn't supported. Save as `.xlsx`.
+
+## Roadmap
+
+Next up: testing against thousands of real workbooks, understanding inserted and moved rows, then code review for spreadsheets: showing what a change does to the numbers, tests that run on every pull request, and a linter. See [ROADMAP.md](ROADMAP.md).
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE).
+
+You can use, change and ship xlgit, including commercially. If you pass it on, modified or not, keep the [NOTICE](NOTICE) file and the copyright line at the top of `xlgit.py` with it. The license doesn't grant use of the xlgit name for your own version.
+
+Created by Michael Fowler.

xlgit-0.1.0/README.md

@@ -0,0 +1,189 @@
+# xlgit
+
+> Beta (0.1.0). Every release is fuzz-tested against thousands of real-world workbooks, but you'll still find cases it gets wrong. Git keeps every version, so a bad merge can always be undone. Please [open an issue](https://github.com/MichaelFowler1/excel-git/issues) when something looks wrong.
+
+Git and GitHub treat `.xlsx` as an opaque binary blob. You can commit, fork and branch it, but a diff just says "binary file changed" and any merge where both sides touched the file is a conflict. This fixes that.
+
+## What you get
+
+| | Without xlgit | With xlgit |
+|---|---|---|
+| `git diff` | `Binary files differ` | `changed Budget!B2 1000 -> 1100`, plus inserted, deleted and moved rows, and chart, image and comment changes |
+| Seeing changes | n/a | `xlgit diff --html`: the sheet as a grid in your browser, changes highlighted |
+| Merge, different cells edited | conflict, pick one whole file | merges cleanly |
+| Merge, one side inserted rows | conflict | the other side's edits follow their rows |
+| Merge, same cell edited | conflict | conflict on just that cell, listed in a `_merge_conflicts` sheet with a link to it |
+| Charts, images, comments, formatting, macros | n/a | kept, and their edits to them carried over |
+| Tables and pivot tables | n/a | merged: you add rows, they add a column, you get both |
+| Pull request on GitHub | "binary file not shown" | bot comment with a table of every changed cell, chart, table and pivot |
+
+Formulas are compared as formulas (`=B2+C2`), not their cached results.
+
+## Get started
+
+You need git. Then, once per computer, either:
+
+**With Python** (3.9 or newer):
+
+```bash
+pip install xlgit
+xlgit install
+```
+
+**Without Python:** download the program for your computer from the [latest release](https://github.com/MichaelFowler1/excel-git/releases/latest) (`xlgit-windows.exe`, `xlgit-macos-arm64` for Apple silicon, `xlgit-macos-intel`, `xlgit-linux`), rename it to `xlgit` (`xlgit.exe` on Windows), put it somewhere it will stay, and run `xlgit install`. On Windows you can also just double-click it and it offers to set itself up. The downloads aren't code-signed yet: on Windows click "More info" then "Run anyway"; on a Mac, right-click it, choose Open, then Open again. If you move the program later, run `xlgit install` again.
+
+That's it. Every git repository on this computer now understands `.xlsx` and `.xlsm` files, including ones you clone or create later. Keep using git the way you already do.
+
+To also get a comment listing the changed cells on every GitHub pull request, run this once inside the repository and push:
+
+```bash
+xlgit install --github
+```
+
+Run `xlgit` on its own at any time to see the commands and check that everything is set up.
+
+## Everyday use
+
+**See what changed.** `xlgit diff` lists every cell that changed in your workbooks since the last commit. Inserted, deleted and moved rows show up as rows, not as every cell below them changing. `git diff`, `git log -p` and `git show` show cell changes too.
+
+```
+$ xlgit diff
+=== budget.xlsx ===
+changed        Budget!C3  350 -> 999
+row inserted   Budget row 4  A: 'Gas', B: 60, C: 70, D: =B4+C4
+changed        Budget!D8  =SUM(D2:D6) -> =SUM(D2:D7)
+```
+
+`xlgit diff --html` opens the same changes in your browser, laid out like the spreadsheet:
+
+<img src="docs/visual-diff.png" alt="Visual diff: a changed cell shows its old value, an inserted row is green, a changed SUM range is highlighted" width="480">
+
+**Merge.** `git merge` and `git pull` combine edits from both branches cell by cell. If you changed different cells, there's nothing to do.
+
+**When both of you changed the same cell**, git stops and xlgit tells you which cells:
+
+```
+xlgit merged budget.xlsx: took 3 cell(s) from the other branch, but 1 change(s) clash.
+  Budget B2: yours 1100, theirs 1200 (was 1000)
+  Your values were kept. Every clash is listed, with a link, on the sheet '_merge_conflicts'.
+```
+
+Open the workbook, go through the `_merge_conflicts` sheet (each row links to its cell), fix the cells, delete that sheet, save, then run `git add budget.xlsx` and `git commit`. Git keeps every version, so nothing is ever lost: `git merge --abort` undoes the whole merge.
+
+## Found a problem?
+
+Please [open an issue](https://github.com/MichaelFowler1/excel-git/issues/new/choose). Bug reports on real workbooks are the most useful thing you can give this project, and you don't have to share your data to do it:
+
+```bash
+xlgit scrub --merge budget.xlsx     # during a merge that went wrong: base, yours, theirs, in one zip
+xlgit scrub old.xlsx new.xlsx       # any workbooks, e.g. for a wrong diff
+```
+
+`scrub` makes copies where every number, piece of text, comment, chart label and file property is replaced with made-up values, keeping formulas, layout, charts, tables and pivots, so the problem still shows up. Equal values stay equal across the files scrubbed together. Sheet names and named ranges are kept (formulas refer to them), macros are removed, and images are replaced with blank ones. Open the copies and check them before you share them.
+
+## How the merge works
+
+A workbook is a zip of XML files: one per sheet, one per chart, one per image and so on. Instead of re-saving the whole thing through a spreadsheet library (which is how charts used to get lost), xlgit starts from your copy's zip and only rewrites the XML that has to change:
+
+- **Cells**: 3-way merge cell by cell. A cell only one side changed takes that side's value.
+- **Rows**: if one branch inserted, deleted or moved rows and the other edited cells, the edits land on the rows where their cells ended up, with formula references renumbered the way Excel does it. An edit to a row the other branch deleted is a conflict.
+- **Charts, images, comments, macros**: 3-way merge object by object. If only their branch changed a chart, you get their version. If both did, yours is kept and it's flagged as a conflict. Chart edits caused by cell changes (Excel caches plotted values inside the chart) don't count as edits.
+- **Tables**: merged field by field. Their new column plus your new rows gives a table with both. Tables added on their branch come over, and if both branches added a `Table2`, theirs is renamed `Table3` and their formulas are updated to match.
+- **Pivot tables**: a pivot, its data cache and the cached records merge as one bundle. A branch that only refreshed a pivot (same layout, new data) doesn't count as an edit, so your data change and their "switch to Average" merge cleanly. New pivots from their branch come over, sharing an existing cache when they used one.
+- **Sheets**: new sheets on their branch come over whole, with their charts, tables and pivots. Renames and deletes merge too.
+- **Named ranges**: merged by name.
+
+Writers renumber a workbook's internal files on every save (add a chart to an early sheet and every later `chart1.xml` becomes `chart2.xml`). xlgit matches objects by what they are, like "the chart called Chart 1 on sheet Notes" or "table id 3", not by file name, so renumbering doesn't cause false conflicts.
+
+Excel recalculates every formula and refreshes affected pivot tables when it opens the merged file.
+
+## Commands
+
+```
+xlgit                        help, and whether everything is set up
+xlgit install                set up every repository on this computer (once)
+xlgit install --github       add pull request comments to this repository
+xlgit install --repo         set up only this repository
+xlgit uninstall [--repo]     undo the setup
+xlgit diff                   what changed in your workbooks since the last commit
+xlgit diff FILE              ... in one workbook
+xlgit diff OLD NEW           compare any two workbooks (--markdown for a table)
+xlgit diff --html [FILES]    open the changes in your browser (--out=page.html to save it)
+xlgit scrub FILE...          copies with every value made up, safe to attach to a bug report
+xlgit scrub --merge FILE     the three versions of a merge that went wrong, scrubbed, in one zip
+xlgit --version
+```
+
+Git runs `xlgit textconv` and `xlgit merge` itself; you don't need to.
+
+Don't want a package? `xlgit.py` is a single file. Copy it in, `pip install openpyxl lxml`, and run `python xlgit.py install`.
+
+### The GitHub Action
+
+`xlgit install --github` writes this workflow. You can also add it by hand:
+
+```yaml
+# .github/workflows/excel-diff.yml
+name: Excel diff
+on:
+  pull_request:
+    paths: ["**/*.xlsx", "**/*.xlsm"]
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  excel-diff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: MichaelFowler1/excel-git@v0.1.0
+```
+
+It keeps one comment per pull request up to date as you push. Pull requests from forks can't be commented on with GitHub's default token, so for those the changed cells go in the run's summary page instead.
+
+## Tests
+
+```bash
+pip install -r requirements-dev.txt
+python -m pytest tests
+```
+
+The tests build workbook versions with charts, comments and named ranges, run real `git merge` through the driver, and check every object survived. Set `XLGIT_KEEP=some/dir` to keep the merged files and open them in Excel yourself.
+
+### Fuzzing against real workbooks
+
+`fuzz/merge_fuzz.py` runs the merge over a folder of real spreadsheets. For each one it makes two branches with random cell edits, merges them, and checks the result: it opens, every edit from both sides is there with its exact type and value, nothing else changed, no chart, table or pivot was lost, and the conflicts reported are exactly the cells both sides changed.
+
+```bash
+pip install py7zr
+fuzz/fetch_corpus.sh corpus            # ~17,000 workbooks: Enron corpus + open-source test suites
+python fuzz/merge_fuzz.py corpus --keep failed/
+```
+
+`--keep` saves the base, ours, theirs and merged files of every failure. `--rounds N` tries N different random edits per workbook.
+
+## Limits
+
+- Formatting changes their branch made to existing cells come over only when both branches have the same set of styles. Otherwise your formatting is kept.
+- Column widths, merged cells and conditional formatting on existing sheets aren't merged. Yours are kept.
+- Until Excel refreshes a merged pivot, the numbers in its cells are the old ones. Excel does this on open, but tools that read the file without Excel (pandas, openpyxl) see the stale values.
+- Slicers, timelines and tables linked to external data connections aren't merged. They're reported as conflicts so nothing disappears silently.
+- If both branches added a chart to a sheet that had none, only yours is kept (flagged).
+- Inserted and deleted rows are followed when only one branch changed a sheet's rows. If both branches inserted or deleted rows on the same sheet, that sheet merges cell by cell, and cells that only moved can show up as conflicts.
+- Rows are recognised by their contents. A row change can't always be recognised (say, deleting one of many identical rows); then the sheet merges cell by cell and anything unclear is reported as a conflict, never guessed.
+- Inserted columns show as changed cells for now.
+- `.xls` (the old pre-2007 format) isn't supported. Save as `.xlsx`.
+
+## Roadmap
+
+Next up: testing against thousands of real workbooks, understanding inserted and moved rows, then code review for spreadsheets: showing what a change does to the numbers, tests that run on every pull request, and a linter. See [ROADMAP.md](ROADMAP.md).
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE).
+
+You can use, change and ship xlgit, including commercially. If you pass it on, modified or not, keep the [NOTICE](NOTICE) file and the copyright line at the top of `xlgit.py` with it. The license doesn't grant use of the xlgit name for your own version.
+
+Created by Michael Fowler.

xlgit-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+# Same floor as cost-core: 77.0.3 is the oldest setuptools that reads the
+# SPDX license string plus license-files (PEP 639) below.
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xlgit"
+version = "0.1.0"
+description = "Cell-level diff and merge for Excel workbooks in git, keeping charts, tables and pivots"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = ["openpyxl>=3.1.0", "lxml>=4.9"]
+# No email: the repository is the contact point. Mirrors CITATION.cff.
+authors = [{ name = "Michael Fowler" }]
+license = "Apache-2.0"
+# NOTICE must travel with every copy, so it ships in the wheel beside LICENSE.
+license-files = ["LICENSE", "NOTICE"]
+keywords = ["excel", "git", "merge", "diff", "xlsx", "spreadsheet", "version-control"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Version Control :: Git",
+    "Topic :: Office/Business :: Financial :: Spreadsheet",
+]
+
+[project.urls]
+Repository = "https://github.com/MichaelFowler1/excel-git"
+Issues = "https://github.com/MichaelFowler1/excel-git/issues"
+
+[project.scripts]
+xlgit = "xlgit:cli"
+
+[tool.setuptools]
+py-modules = ["xlgit"]

xlgit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+