# SaveUtils – FreeCAD Workbench Addon

![SaveUtils Example in the FreeCAD File menu](https://jefftml.s3.amazonaws.com/thumbs/SaveUtilsExample2.png)

[SaveUtils](https://github.com/jefe317/SaveUtils/) adds four convenience commands to FreeCAD's **File** menu:

| Command | What it does |
|---|---|
| **Save with Timestamp** | Saves as `<basename>-YYYYMMDD-HHMMSS.FCStd` |
| **Save Increment** | Saves as the next `<basename>-01.FCStd`, `…-02.FCStd` |
| **Save As with Timestamp** | Asks for a base filename, then saves as `<base>-YYYYMMDD-HHMMSS.FCStd` |
| **Save As Increment** | Asks for a base filename, then saves as the next `<base>-01.FCStd`, `…-02.FCStd` |

All four save the document under the new name and **leave you working in that new file**, exactly
like FreeCAD's own *Save As*. The file you started in stays on disk as it last was.

The difference between the two pairs is only where the name comes from:

- The **Save** commands derive it automatically from the open document — no dialog.
- The **Save As** commands open a file dialog so you pick the base name yourself.

## Behavior details

### Naming
- **Timestamp** commands append `-YYYYMMDD-HHMMSS.FCStd`. If the name already ends with that
  pattern it is **replaced**, not doubled:  
  `design-20240101-120000.FCStd` → `design-20240315-093045.FCStd`
- **Increment** commands append `-NN.FCStd`, zero-padded to 2 digits. The folder is scanned for
  existing `<basename>-NN.FCStd` files and the **highest number found is incremented**, so
  repeated use never overwrites an earlier snapshot:  
  `design.FCStd` with `design-01`/`design-02` on disk → `design-03.FCStd`
- Only counters directly following the basename count, so `design-detail-01.FCStd` does not
  affect `design`'s numbering.
- If the open file is itself an increment (`design-03.FCStd`), the basename is `design`.

### Unsaved documents
A document that has never been saved has no name to derive from, so the **Save** commands fall
back to the same file dialog the **Save As** commands use.

### The chosen name is a *base*
In the **Save As** commands the name you pick in the dialog is the base, not the final filename —
picking `design.FCStd` writes `design-20240315-093045.FCStd`. Nothing is written to the name you
typed, which is why the dialog does not ask about overwriting it.

## Installation

### Manual

Add this repository to your Addon Custom Repositories
1. In FreeCAD, go to Edit > Preferences > Addon Manager.
2. Under Costom Repositories, click the green plus button to Add https://github.com/jefe317/SaveUtils/ with the branch main.
3. Click Apply, close the Preferences window.
4. In Tools > Addon Manager, you can now search for "SaveUtils" and install it via the Install button.
5. Restart FreeCAD.  
   The four items appear near the top of the **File** menu.

### Via Addon Manager

If this repo is listed in a custom addon source, you can install it through  
**Tools > Addon Manager > Search for SaveUtils > Install**.

## Requirements

- FreeCAD 0.20 or later  
- PySide2 (bundled with FreeCAD)

## License

GPL v3