DateForge

A polished Python timestamp toolkit for changing the date modified value of files and folders from a clean hacker-terminal styled launcher.
Single files, folders, recursive folder updates, undo history, batch updates, saved presets, filters, Windows created-time support, and friendly time shortcuts all run from one lightweight console tool.

Workflow | Features | Setup | Commands | Time Formats | Development

            ____        _       _____
           |  _ \  __ _| |_ ___|  ___|__  _ __ __ _  ___
           | | | |/ _` | __/ _ \ |_ / _ \| '__/ _` |/ _ \
           | |_| | (_| | ||  __/  _| (_) | | | (_| |  __/
           |____/ \__,_|\__\___|_|  \___/|_|  \__, |\___|
                                              |___/

Built for quick local file work: pick a target, choose the modified time you want, and let DateForge update metadata without editing file contents. Every successful update is logged so the last DateForge change can be restored.

Timestamp Workflow

1. Choose A Target Paste, type, or drag a file/folder path into the launcher or CLI.

2. Set The Time Use a full timestamp like 2026-05-15 18:30:00, or a shortcut like today 18:30, tomorrow 09:00, or now.

3. Forge Metadata Apply modified and optional created timestamps while DateForge shows each processed target and records an undoable history entry.

At A Glance

Terminal Launcher Green-on-black console style, ASCII banner, boot rows, and command prompts.

Timestamp Engine Updates modified-time metadata while preserving access time by default.

Folder Control Update a folder itself, recursively process children, or filter by glob.

Undo History Restore the most recent DateForge change or inspect the history log.

Features

Styled launcher menu Open run.bat on Windows for the full DateForge console with neon status rows, access messages, and a simple numbered menu.	Direct CLI commands Run dateforge.py, the installed dateforge command, or the legacy timewarp aliases when you want one-shot terminal usage.
Single target updates Change the modified timestamp for one file or one folder without editing its contents.	Recursive folder updates Process everything inside a folder, then reset the root folder timestamp last. Include and exclude glob filters can limit which targets are touched.
Human-friendly time input Accepts exact date/time values plus shortcuts like now, noon, midnight, today 18:30, and 6:30pm.	No third-party dependencies Uses the Python standard library only, so setup stays small and local.
Undo and history log Every successful update is written to a local JSONL history file. Run --undo to restore the latest unapplied DateForge change.	Batch files and presets Update many paths from a text file, save named timestamp presets, and reuse those presets from either modified-time or created-time commands.
Windows created time On Windows, DateForge can update file/folder created time with --created while still supporting modified-time changes.	Local-only storage Presets and history are stored on your machine under the DateForge app data folder by default.

Setup

1. Clone or download the project.

git clone https://github.com/Kieranmcm07/DateForge.git
cd DateForge

2. Start the Windows launcher.

run.bat

3. Or run it from PowerShell.

py launcher.py

If the Python launcher is not available on your machine, use your normal Python command instead:

python launcher.py

Windows Helper Script

The repository includes one Windows batch file for quick local use:

Script	Purpose
run.bat	Open the styled DateForge launcher menu

Command Overview

Run directly from the project root:

py dateforge.py "C:\path\to\file.txt" --time "2026-05-15 18:30:00"

Command / Option	Description
py launcher.py	Open the interactive DateForge launcher
py dateforge.py	Run the CLI from the repository root
dateforge	Installed console command after pip install -e .
timewarp	Legacy command alias
timewarp-file	Legacy command alias
PATH	File or folder to update
--time "YYYY-MM-DD HH:MM:SS"	Desired modified timestamp
--created "YYYY-MM-DD HH:MM:SS"	Desired Windows created timestamp
--recursive	Update child files and folders when the target is a folder
--include "*.txt"	Only update targets matching a glob pattern
--exclude "*.bak"	Skip targets matching a glob pattern
--batch targets.txt	Read target paths from a text file
--preset NAME	Use a saved preset as the modified timestamp
--save-preset NAME TIME	Save a reusable timestamp preset
--delete-preset NAME	Delete a saved preset
--list-presets	Show saved presets
--history [N]	Show recent history entries
--undo	Restore the latest unapplied DateForge change
--no-banner	Hide the ASCII banner for cleaner command output
--quiet	Print only errors and the final count

Quick Examples

Update one file:

py dateforge.py "C:\path\to\file.txt" --time "2026-05-15 18:30:00"

Update a folder itself:

py dateforge.py "C:\path\to\folder" --time "2026-05-15 18:30:00"

Update every item inside a folder too:

py dateforge.py "C:\path\to\folder" --time "2026-05-15 18:30:00" --recursive

Update only text files in a folder tree:

py dateforge.py "C:\path\to\folder" --time "2026-05-15 18:30:00" --recursive --include "*.txt"

Skip temporary files during a recursive update:

py dateforge.py "C:\path\to\folder" --time "2026-05-15 18:30:00" --recursive --exclude "*.tmp"

Update Windows created time too:

py dateforge.py "C:\path\to\file.txt" --time "2026-05-15 18:30:00" --created same

Update targets from a batch file:

py dateforge.py --batch targets.txt --time "2026-05-15 18:30:00"

Save and use a preset:

py dateforge.py --save-preset release "2026-05-15 18:30:00"
py dateforge.py "C:\path\to\file.txt" --preset release

Show history or undo the latest DateForge change:

py dateforge.py --history
py dateforge.py --undo

Accepted Time Formats

Recommended formats:

YYYY-MM-DD HH:MM
YYYY-MM-DD HH:MM:SS
YYYY-MM-DDTHH:MM:SS
YYYY/MM/DD HH:MM
YYYY/MM/DD HH:MM:SS
today HH:MM
tomorrow HH:MM
yesterday HH:MM

Also supported:

MM/DD/YYYY HH:MM
MM/DD/YYYY HH:MM:SS
now
noon
midnight

Examples:

2026-05-15 18:30
2026-05-15 18:30:45
2026/05/15 18:30
05/15/2026 18:30
today 18:30
tomorrow 09:00
yesterday
6:30pm
now

Install As A CLI

From the project root:

py -m pip install -e .

Then run:

dateforge "C:\path\to\file.txt" --time "2026-05-15 18:30:00"

The older timewarp and timewarp-file commands are also kept as aliases.

Data And Behaviour Notes

• DateForge changes timestamp metadata only. It does not edit file contents.
• DateForge can also change Windows created time when --created is used.
• Access time is preserved while modified time is changed.
• On folders, --recursive updates child files and folders before resetting the root folder timestamp.
• --include and --exclude accept glob patterns and can be repeated.
• Batch files use one target path per line. Blank lines and lines starting with # are ignored.
• Successful updates are recorded in a local history log so --undo can restore the latest unapplied change.
• Presets and history are stored in the DateForge app data folder by default.
• Some protected files may require elevated permissions.
• DateForge uses your local system timezone by default.

Project Structure

.
|-- src/
|   `-- timewarp_file/
|       |-- __init__.py
|       |-- __main__.py
|       |-- cli.py
|       |-- console.py
|       |-- history.py
|       |-- presets.py
|       `-- timestamp.py
|-- tests/
|   |-- __init__.py
|   |-- test_features.py
|   `-- test_timestamp.py
|-- dateforge.py
|-- launcher.py
|-- timewarp.py
|-- run.bat
|-- pyproject.toml
|-- LICENSE
`-- README.md

Development

Install the project in editable mode:

py -m pip install -e .

Run the test suite:

py -m unittest discover

Show the CLI help:

py dateforge.py --help

License

This project is licensed under the MIT License.