https://github.com/rubicon/rubicon_set_future_file_added_date
A lightweight macOS CLI that sets a file’s Finder “Date Added” and aligns “Date Modified” for demos, automation, and reproducibility — even for future timestamps.
https://github.com/rubicon/rubicon_set_future_file_added_date
automation bash cli developer-tools file-date file-date-changer finder macos metadata spotlight timestamp
Last synced: about 2 hours ago
JSON representation
A lightweight macOS CLI that sets a file’s Finder “Date Added” and aligns “Date Modified” for demos, automation, and reproducibility — even for future timestamps.
- Host: GitHub
- URL: https://github.com/rubicon/rubicon_set_future_file_added_date
- Owner: rubicon
- License: mit
- Created: 2025-11-06T15:10:58.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-07-02T20:55:28.000Z (about 7 hours ago)
- Last Synced: 2026-07-02T22:10:13.558Z (about 6 hours ago)
- Topics: automation, bash, cli, developer-tools, file-date, file-date-changer, finder, macos, metadata, spotlight, timestamp
- Language: Shell
- Homepage: https://github.com/rubicon/rubicon_set_future_file_added_date
- Size: 30.3 KB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Rubicon: Set Future File Added Date
A tiny, focused macOS CLI that sets a file’s Finder **Date Added** (and aligns **Date Modified**) to a specified instant — useful for demos, metadata control, Dock behavior tuning, and automation workflows.
> Works on macOS only. Requires Xcode Command Line Tools for a small helper build step.
## Features
- Set Finder **Date Added** to an exact timestamp
- Align filesystem **Date Modified** (mtime) accordingly and report any OS clamping
- Idempotent and chatty: prints before/after from both Spotlight (`mdls`) and filesystem (`stat`)
- No external deps beyond standard macOS toolchain
## Common Use Cases
- **Dock Overlay Icons** — Set file “Date Added” timestamps to control the sort order and overlay indicators in your **Downloads stack** or Dock folders. Perfect for showcasing files at the top without renaming them.
- **Demo Preparation** — Stage datasets, screenshots, or project assets so they appear freshly added.
- **Data Migration Testing** — Validate timestamp preservation or system behavior with future or synthetic dates.
- **Forensics & Metadata Research** — Explore how macOS stores and displays time-based metadata across versions.
## Quickstart
```bash
# clone
git clone https://github.com/rubicon/rubicon_set_future_file_added_date.git
cd rubicon_set_future_file_added_date
# run
./rubicon_set_future_file_added_date.sh /path/to/file --date "2035-11-06T14:29:09Z"
```
If `--date` is omitted, the script defaults to **10 years in the future**.
**Needs Verification:** confirm the default offset matches your version of macOS.
## Install (optional symlink)
```bash
sudo make install # installs to /usr/local/bin (or /opt/homebrew/bin on Apple Silicon)
rubicon-set-date --help
```
## Usage
```bash
./rubicon_set_future_file_added_date.sh [--date ""]
```
- `--date` accepts ISO 8601, e.g. `2025-12-31T23:59:59Z`.
Local times are parsed by macOS `date` and converted to UTC.
**Needs Verification:** locale handling for non-`en_US.UTF-8`.
### Behavior Notes
- macOS may clamp impossible future mtimes; the script reports the actual result.
- Spotlight metadata updates can be asynchronous; this script reindexes and verifies the final state.
## Badges
[](https://github.com/rubicon/rubicon_set_future_file_added_date/actions/workflows/ci.yaml)
[](https://github.com/rubicon/rubicon_set_future_file_added_date/releases)
[](LICENSE)
[](https://github.com/rubicon/rubicon_set_future_file_added_date/commits)
## Development
```bash
# format & lint
make fmt
make lint
# run tests (smoke tests only)
make test
```
### Tooling
- **shfmt** for formatting
- **shellcheck** for static analysis
- **bats** for lightweight testing
- **release-please** for automated versioning and changelog updates
Install tools on macOS:
```bash
brew install shellcheck shfmt bats-core
```
## Contributing
We use Conventional Commits and automated releases.
See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
## Security
Please report vulnerabilities responsibly through [SECURITY.md](SECURITY.md).
No guarantees are made; see [LICENSE](LICENSE) for terms.
## License
MIT © 2025 Dax Davis
## Social Preview
For better share cards, set a repository social preview image — for example,
a Finder window with a highlighted **Date Added** column and a subtle forward arrow motif.