[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80155":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":14,"stars30d":16,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":17,"rankGlobal":10,"rankLanguage":10,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":10,"pushedAt":10,"updatedAt":30,"readmeContent":31,"aiSummary":32,"trendingCount":15,"starSnapshotCount":15,"syncStatus":13,"lastSyncTime":33,"discoverSource":34},80155,"HistoryWorkbench","eblanshey\u002FHistoryWorkbench","eblanshey","A FreeCAD workbench to track CAD model history and review changes using 3D and tree comparisons.","",null,"Python",61,2,1,0,9,42.83,"GNU Lesser General Public License v2.1",false,"master",true,[23,24,25,26,27,28,29],"addon","cad","diff","freecad","git","plm","versioning","2026-06-12 04:01:26","# History Workbench for FreeCAD\n\n## Track CAD model history and review changes using 3D and tree comparisons.\n\n\u003Ca href=\"https:\u002F\u002Fwww.freecad.org\u002F\">\u003Cimg alt=\"FreeCAD 1.1+\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FFreeCAD-1.1%2B-blue\">\u003C\u002Fa>\n\n![3d comparison image](https:\u002F\u002Fraw.githubusercontent.com\u002Feblanshey\u002FHistoryWorkbench\u002Fmaster\u002Ffreecad\u002Fhistory_wb\u002Fresources\u002Fmedia\u002F3d-comparison.png)\n\n![tree comparison image](https:\u002F\u002Fraw.githubusercontent.com\u002Feblanshey\u002FHistoryWorkbench\u002Fmaster\u002Ffreecad\u002Fhistory_wb\u002Fresources\u002Fmedia\u002Ftree-comparison.png)\n\n## Intro\n\nHistory Workbench helps you create CAD projects with confidence by tracking iterations over time, reviewing in-progress work, restoring models from saved history, and showing model changes as detailed 3D and parametric tree comparisons.\n\nIt helps answer questions like:\n\n- How does my change look in 3D compared to the last iteration?\n- Can I trust that my changes didn't create any unforeseen side-effects?\n  - FreeCAD core and workbench development: what else did my new feature or bugfix affect?\n- Which objects, dimensions, placements, expressions, or dependencies changed?\n- What did my model look like 3 iterations ago?\n- Why did I change this model 2 months ago?\n\nHistory Workbench uses Git internally for version control, but Git knowledge is not required for normal use. The workbench intentionally replaces Git terminology with CAD-focused terms, such as **Project**, **Iteration**, and **Review**, so the workflow matches how CAD users think about model history.\n\n> [!NOTE]\n> This workbench is relatively new. We try to avoid backwards-incompatible changes but they are still possible. Sharing feedback, opening issues, and submitting pull requests are encouraged!\n\n## Features\n\n- **3D feature comparison:** Open visual comparisons for Part, PartDesign, and Sketcher objects, with added, removed, and shared geometry shown in separate colors.\n- **Model tree comparison:** See added, removed, and modified objects in FreeCAD's model tree hierarchy with color-coded highlighting\n- **Detailed property review:** Inspect exact changes to dimensions, placements, expressions, constraints, quantities, links, and other editable properties.\n- **Review workflow:** Review model changes incrementally and save the result as a new iteration when ready.\n- **Project history timeline:** Move between in-progress work, reviewed changes, and saved iterations from one history panel.\n- **Safe restore workflow:** Restore individual files or batches from **Reviewed** or any saved iteration back onto disk without rewriting project history.\n- **Multi-document support:** Review and iterate on multiple related documents at once, such as assemblies spread across several `.FCStd` files.\n- **Noise control:** Hide generated object types or properties, tune floating-point precision, and keep comparisons focused on meaningful CAD changes.\n- **Light and dark theme support:** Keep comparison highlights readable in both light and dark FreeCAD themes.\n- **Local-first storage:** your project stays on your computer. Optional remote storage and sharing available for advanced users.\n\n## Installation\n\nHistory Workbench requires:\n\n- FreeCAD 1.1 or newer (earlier versions may work, but are untested)\n- Git installed and available on your computer for iteration tracking. **Knowledge of Git is not required to use this workbench.**\n  - Install it from \u003Chttps:\u002F\u002Fgit-scm.com\u002Finstall>. Run the installer with default options.\n\nHistory Workbench is not yet available in the official FreeCAD Addon Manager repository. Until then, install it as a custom repository:\n\n1. Open FreeCAD.\n2. Go to **Edit > Preferences > Addon Manager > Custom repositories**.\n3. Add this repository URL: `https:\u002F\u002Fgithub.com\u002Feblanshey\u002FHistoryWorkbench`\n4. Set the branch to `master`.\n5. Open **Tools > Addon Manager**.\n6. Search for **History Workbench** and install it.\n7. Restart FreeCAD.\n\n### Upgrading\n\nWhen upgrading from an existing Addon Manager installation:\n\n1. Open **Tools > Addon Manager**.\n2. Uninstall **History Workbench**.\n3. Close FreeCAD.\n4. Reopen FreeCAD.\n5. Open **Tools > Addon Manager**.\n6. Install **History Workbench** again.\n7. Restart FreeCAD.\n\n## First Run: Project Initialization\n\nHistory Workbench works with a Project: a folder on your computer that contains the FreeCAD files you want to track together. For an existing folder of CAD files, initialize it as a Project first, then save a baseline iteration before making new CAD changes so tree comparisons have a starting point.\n\n1. **(Recommended) FreeCAD compression:** To keep project history more storage-efficient, see the FreeCAD Version Storage Tips section below.\n2. **Open a FreeCAD file:** Start FreeCAD and open any document from the folder you want to use as the root of your Project.\n3. **Initialize the Project:** Click \u003Cimg src=\"freecad\u002Fhistory_wb\u002Fresources\u002Ficons\u002FCreateGitRepository.svg\" width=\"16\" alt=\"\" \u002F> **Initialize Project** in the History Workbench, select the folder that contains your project files, and click \"Initialize\".\n4. **Open project documents:** Click \u003Cimg src=\"freecad\u002Fhistory_wb\u002Fresources\u002Ficons\u002FRefreshRepository.svg\" width=\"16\" alt=\"\" \u002F> **Refresh Project**, then click \u003Cimg src=\"freecad\u002Fhistory_wb\u002Fresources\u002Ficons\u002FOpenAllDocuments.svg\" width=\"16\" alt=\"\" \u002F> **Open All Documents** to open all FreeCAD documents in the project folder.\n5. **Recompute documents:** Click \u003Cimg src=\"freecad\u002Fhistory_wb\u002Fresources\u002Ficons\u002FRecomputeAll.svg\" width=\"16\" alt=\"\" \u002F> **Recompute All** to make sure document state is current. Ensure there aren't recomputation errors.\n6. **Review current file state:** Select **Current Files** in the history list. Large projects may take some time while comparison data is generated.\n7. **Mark everything reviewed:** Click **Mark All Reviewed**. The workbench saves documents and records the tree structure data needed for future comparisons.\n8. **Save the baseline iteration:** Use \u003Cimg src=\"freecad\u002Fhistory_wb\u002Fresources\u002Ficons\u002FCommit.svg\" width=\"16\" alt=\"\" \u002F> **Save Iteration** or your regular version-control client.\n\nAfter that baseline iteration, continue modeling normally and use the Daily Workflow instructions below to review your work.\n\n## Daily Usage\n\nUse History Workbench as a review loop after normal CAD work.\n\n1. **Work in FreeCAD as usual:** Model, recompute, save, and edit your project files normally. Recompute your document(s) and ensure there are no errors.\n2. **Refresh the project:** In the History workbench, click \u003Cimg src=\"freecad\u002Fhistory_wb\u002Fresources\u002Ficons\u002FRefreshRepository.svg\" width=\"16\" alt=\"\" \u002F> **Refresh Project** so the history list and document status reflect the latest files.\n3. **Review file changes:** Click the **Current Files** iteration item in the list. The document tree shows added, removed, and modified objects since the last reviewed state.\n4. **Inspect detailed properties:** Click a changed object in the model tree. The property panel shows changed dimensions, placements, expressions, constraints, quantities, links, and other editable properties.\n5. **Open 3D comparisons:** For changed Part, PartDesign, or Sketcher objects, click \u003Cimg src=\"freecad\u002Fhistory_wb\u002Fresources\u002Ficons\u002FVisualDiff.svg\" width=\"16\" alt=\"\" \u002F> **3D Comparison** next to the object to open a separate comparison document. Removed material is shown in red, added material in green, and unchanged material in gray. You may use FreeCAD's unified measurement tool to measure changes.\n6. **Mark documents reviewed:** Click the **Reviewed** button on individual documents when they are ready, or click **Mark All Reviewed** after reviewing all of them. This supports incremental review across multiple related files, such as assemblies.\n7. **Keep working if needed:** Return to the CAD model and make more edits, if needed. The next **Current Files** comparison is made against the documents you already marked as reviewed.\n8. **Verify reviewed work:** Click the **Reviewed** iteration item in the history list to confirm exactly what will be saved in the next iteration.\n9.  **Save an iteration:** Click \u003Cimg src=\"freecad\u002Fhistory_wb\u002Fresources\u002Ficons\u002FCommit.svg\" width=\"16\" alt=\"\" \u002F> **Save Iteration**, enter a description of the changes, and confirm.\n\n> [!CAUTION]\n> Tree comparisons focus on structured FreeCAD object and property data, but may not capture every CAD model change yet. Use 3D comparisons as an additional review step before saving an iteration.\n\n### Restoring Files from Reviewed or Saved Iterations\n\nUse restore when you want to bring one file, or many files, back to a prior saved state on disk.\n\n1. Select **Reviewed** or a specific saved iteration in the history list.\n2. Restore one file with the per-file **Restore** button, or restore many files with **Restore All**.\n3. For **Restore All**, choose a scope:\n   - **Listed FreeCAD files:** Restore only the FreeCAD files changed in the selected iteration.\n   - **All FreeCAD files:** Restore all previously saved FreeCAD files to how they were in this iteration. Any previously saved FreeCAD files that did not exist in that iteration are removed. New files not yet saved to history are kept.\n4. Confirm the warning dialog.\n\nRestore behavior:\n\n- Restore changes files on disk only; saved iteration history is unchanged.\n- Open project documents are closed before restore and reopened after restore.\n- Unsaved in-memory changes in those project documents are lost.\n- New FreeCAD files not yet saved in history are left unchanged during **All FreeCAD files** restore.\n\nTo preserve project history, previous iterations cannot be altered once they are saved.\n\n## Commands\n\n| Command | Icon | Description |\n|---------|------|-------------|\n| Open History Panel | \u003Cimg src=\"freecad\u002Fhistory_wb\u002Fresources\u002Ficons\u002FLogo.svg\" width=\"32\" alt=\"\" \u002F> | Open or focus the History panel. Use it to quickly switch to the history window if it has gone out of focus. |\n| Refresh Project | \u003Cimg src=\"freecad\u002Fhistory_wb\u002Fresources\u002Ficons\u002FRefreshRepository.svg\" width=\"32\" alt=\"\" \u002F> | Refresh the detected project and reload iterations. If an iteration is already selected, the tree comparison is refreshed. Use it when opening FreeCAD documents located within a project and after making any changes. |\n| Recompute Active Document | \u003Cimg src=\"freecad\u002Fhistory_wb\u002Fresources\u002Ficons\u002FRecomputeActiveDocument.svg\" width=\"32\" alt=\"\" \u002F> | Recompute the active document. Use it when you need to recompute only the currently active document. |\n| Recompute All | \u003Cimg src=\"freecad\u002Fhistory_wb\u002Fresources\u002Ficons\u002FRecomputeAll.svg\" width=\"32\" alt=\"\" \u002F> | Recompute every open document. Use it to ensure all document state is current before doing reviews. Useful for projects with many document inter-dependencies. |\n| Open All Documents in Project | \u003Cimg src=\"freecad\u002Fhistory_wb\u002Fresources\u002Ficons\u002FOpenAllDocuments.svg\" width=\"32\" alt=\"\" \u002F> | Open every `.FCStd` file found in the project. Useful for initializing a project. |\n| Initialize Project | \u003Cimg src=\"freecad\u002Fhistory_wb\u002Fresources\u002Ficons\u002FCreateGitRepository.svg\" width=\"32\" alt=\"\" \u002F> | Initialize a new project for the selected directory. Use it when setting up a new folder of CAD files for the first time. |\n| Close Comparison Windows | \u003Cimg src=\"freecad\u002Fhistory_wb\u002Fresources\u002Ficons\u002FDiffCloseDiffWindows.svg\" width=\"32\" alt=\"\" \u002F> | Close every document starting with `Diff_` without saving. Use it when you want to quickly clean up comparison windows after reviewing 3D diffs. |\n| Save Iteration | \u003Cimg src=\"freecad\u002Fhistory_wb\u002Fresources\u002Ficons\u002FCommit.svg\" width=\"32\" alt=\"\" \u002F> | Save reviewed changes as an iteration. Use it after reviewing and marking documents as reviewed to save the result. |\n| Configure Author | \u003Cimg src=\"freecad\u002Fhistory_wb\u002Fresources\u002Ficons\u002FConfigureGit.svg\" width=\"32\" alt=\"\" \u002F> | Configure iteration author name and email. Visible in the menu only. |\n| Edit Ignored Files | \u003Cimg src=\"freecad\u002Fhistory_wb\u002Fresources\u002Ficons\u002FGitIgnore.svg\" width=\"32\" alt=\"\" \u002F> | Edit project's ignored files list (`.gitignore` content). Visible in the menu only. |\n\n## Roadmap\n\n- [ ] Detect `.FCStd` file renames and moves, and update snapshots to match\n- [ ] Create a more in-depth public documentation site\n- [ ] Implement \"File Save History\" to be able to restore any previous file save (include configurable retention and diffing)\n- [ ] Track and compare non-FCStd files in the project\n- [ ] Ability to regenerate historical snapshots (discussion in https:\u002F\u002Fgithub.com\u002Feblanshey\u002FHistoryWorkbench\u002Fissues\u002F5)\n\nDone:\n\n- [x] Move reviewed documents back to Current Files from inside History Workbench\n- [x] Initialize new project history repositories from inside History Workbench\n- [x] 3D view comparisons\n\n## Configuration\n\nFreeCAD's Preferences dialog includes a **History** panel.\n\n### Exclusion Lists\n\nExclusion lists hide noisy generated data from tree comparison views.\n\nEach exclusion list supports two modes:\n\n- **Use default exclusion list:** Use History Workbench's built-in defaults.\n- **Use custom exclusion list:** Provide your own exclusions.\n\nDefault values are defined in [`freecad\u002Fhistory_wb\u002Fdomain\u002Fconfig.py`](freecad\u002Fhistory_wb\u002Fdomain\u002Fconfig.py).\n\n#### Excluded Object Types\n\nEnter one FreeCAD `TypeId` per line, such as `App::Origin`. Objects of these types and their children are removed from comparison views. You can see an object's type by hovering your mouse over it in the History's tree panel.\n\n#### Excluded Properties\n\nEnter one property name per line, such as `TimeStamp`. These properties are excluded across all object types.\n\n#### Type-Specific Excluded Properties\n\nEnter one mapping per line in the format `TypeId -> PropertyName`. This excludes one property for one object type while keeping it visible elsewhere.\n\n```text\nTechDraw::DrawSVGTemplate -> PageResult\n```\n\n### Numeric Comparison\n\n#### Float Precision\n\nSet the number of decimal places used for floating-point comparison and display. The supported range is `0` to `12`; the default is `2`.\n\n## FAQ\n\n### The tree comparison doesn't show any changes, but the Reviewed button is enabled. Why?\n\nNo object or property changes were detected, but the FreeCAD document changed on disk. This can happen when the document was saved without model changes, view properties or internal cache data changed, or parametric changes occurred that History Workbench does not detect yet.\n\nSome of these scenarios are legitimate project changes and should be tracked like any other change. If you find a parametric model change that is not shown in the tree comparison, please open an issue with a sample file when possible.\n\n## FreeCAD Version Storage Tips\n\nFreeCAD documents are binary files by default. Small model edits can produce large file changes, and project history disk usage can grow quickly over time.\n\nFor a simple version-control-friendly setup, disable document compression:\n\n1. Open **Edit > Preferences > General > Document**.\n2. Set **Document save compression level** to `0`.\n\nAn `.FCStd` file is a ZIP archive. With compression disabled, more of the document remains plain XML inside the archive, which makes version storage and external comparison tooling behave better.\n\n*Advanced users:* For large or long-lived CAD projects, also consider Git LFS for `.FCStd` files. There is a [PR in FreeCAD](https:\u002F\u002Fgithub.com\u002FFreeCAD\u002FFreeCAD\u002Fpull\u002F28312) that addresses file formats for versioning. See [this comment](https:\u002F\u002Fgithub.com\u002FFreeCAD\u002FFreeCAD\u002Fissues\u002F11936#issuecomment-4054297851) for more version-control discussions.\n\n## Advanced Usage\n\nThis section is for advanced users who want more control over project history. History Workbench uses Git for version control, so users familiar with Git can use regular Git tools alongside the workbench for workflows that are not implemented in the FreeCAD interface yet.\n\nAdvanced Git usage can help with tasks such as:\n\n- Editing saved iteration messages (Git commit messages).\n- Adding non-FreeCAD files to the **Reviewed** area (Git staging area) so they are saved with the same iteration, such as text documents, spreadsheets, CSV files, or reference data.\n- Backing up a Project to a remote repository (Git remote), such as GitHub, GitLab, or a private Git server.\n- Inspecting project history from external Git clients when you need lower-level version-control tools.\n\nHistory Workbench still needs to be used to mark FreeCAD documents as **Reviewed** (staged). This step stores YAML snapshot files in the Project repository, which are needed to display the document tree.\n\n## Contributors\n\nThis workbench is made for all FreeCAD users. Please open an issue to report bugs, confusing comparisons, setup problems, documentation gaps, or feature requests. Development so far has happened on Linux, so additional platform setup notes and test instructions are also welcome as contributions.\n\n- [Development setup](docs\u002FDevSetup.md): Set up a live FreeCAD workbench checkout, install dependencies, and configure the FreeCAD AppImage runtime for tests.\n- [Development guidelines](docs\u002FDevelopment.md): Coding standards, testing strategy, logging, translations, dependency injection, and common contributor workflows.\n- [Architecture](docs\u002FArchitecture.md): Layer responsibilities, runtime flow, composition roots, and snapshot\u002Fcomparison pipeline.\n","History Workbench 是一个 FreeCAD 插件，用于跟踪 CAD 模型的历史记录并通过 3D 和树状比较来审查更改。它利用 Git 进行版本控制，但用户无需具备 Git 知识即可使用。核心功能包括直观的 3D 特征比较、模型树对比以及详细的属性审查等，这些都帮助用户更准确地理解每次迭代中的变化细节。此外，它还支持多文档操作和自定义显示设置，确保在不同工作环境下都能保持良好的用户体验。适用于需要频繁修改并希望追踪每一步变更的 CAD 设计项目，特别是在团队协作或个人长期维护复杂模型时尤为有用。","2026-06-11 03:59:28","CREATED_QUERY"]