202 lines
4.8 KiB
Text
202 lines
4.8 KiB
Text
# Sapling 🌱
|
|
|
|
Sapling is a Git-native Markdown workspace for writing, research, documentation, and knowledge management.
|
|
|
|
Unlike traditional note-taking applications where version control is an afterthought, Sapling treats Git as a first-class concept. Projects are repositories, history is preserved through commits, attachments are tracked through Git LFS, and complex workspaces can be composed using Git submodules.
|
|
|
|
Sapling is designed to remain entirely client-side. Your files stay on your machine, your projects remain standard Git repositories, and synchronization is handled through any Git remote of your choice.
|
|
|
|
## Vision
|
|
|
|
Sapling aims to provide:
|
|
|
|
- A modern Markdown editing experience
|
|
- Native Git-based versioning
|
|
- Repository portability
|
|
- Long-term ownership of data
|
|
- No proprietary sync service
|
|
- No vendor lock-in
|
|
|
|
Your files are just files.
|
|
|
|
Your projects are just Git repositories.
|
|
|
|
## Core Concepts
|
|
|
|
### Workspace
|
|
|
|
A workspace is a local container for files, folders, and projects.
|
|
|
|
Workspaces are not versioned.
|
|
|
|
They may contain:
|
|
|
|
- Notes
|
|
- Scratch documents
|
|
- Local folders
|
|
- Sapling projects
|
|
|
|
### Project
|
|
|
|
A project is a Git repository.
|
|
|
|
Projects support:
|
|
|
|
- Local commits
|
|
- Branches
|
|
- Tags
|
|
- Remotes
|
|
- Push and pull
|
|
- Merge operations
|
|
- Git LFS
|
|
- Submodules
|
|
|
|
Projects can be opened and managed through the graphical interface or external Git tooling.
|
|
|
|
### Subprojects
|
|
|
|
Projects may contain subprojects through Git submodules.
|
|
|
|
Subprojects behave as independent repositories while remaining integrated into the parent project.
|
|
|
|
Typical use cases:
|
|
|
|
- Research repositories
|
|
- Shared assets
|
|
- Documentation libraries
|
|
- Reusable knowledge bases
|
|
|
|
## Features
|
|
|
|
### Markdown Editor
|
|
|
|
- Live hybrid Markdown editing
|
|
- Markdown source on the active line
|
|
- Rendered Markdown everywhere else
|
|
- Syntax highlighting
|
|
- Live preview
|
|
|
|
### Rendering
|
|
|
|
Initial support includes:
|
|
|
|
- Markdown
|
|
- LaTeX
|
|
- Mermaid diagrams
|
|
- Image embedding
|
|
|
|
Future support may include:
|
|
|
|
- Audio
|
|
- Video
|
|
- PDFs
|
|
- Advanced diagrams
|
|
- Interactive content
|
|
|
|
### Attachments
|
|
|
|
Attachments are stored within projects and tracked through Git LFS.
|
|
|
|
Examples:
|
|
|
|
- Images
|
|
- PSD files
|
|
- Design assets
|
|
- PDFs
|
|
- Binary resources
|
|
|
|
Non-Markdown files are opened using the operating system's default application.
|
|
|
|
### Git Integration
|
|
|
|
Git is a first-class citizen.
|
|
|
|
Supported operations include:
|
|
|
|
- Repository creation
|
|
- Clone
|
|
- Commit
|
|
- Push
|
|
- Pull
|
|
- Branch management
|
|
- Merge workflows
|
|
- History browsing
|
|
- Submodule management
|
|
|
|
Advanced users can open any project in a terminal and use Git directly.
|
|
|
|
## Platform Support
|
|
|
|
### macOS
|
|
|
|
Primary target platform.
|
|
|
|
Uses native macOS technologies and integrates with the system Git installation.
|
|
|
|
### iOS
|
|
|
|
Future target platform.
|
|
|
|
Will share as much code as possible with the macOS application while providing an embedded Git implementation suitable for iOS.
|
|
|
|
## Principles
|
|
|
|
- Local-first
|
|
- Git-native
|
|
- Markdown-first
|
|
- Open source
|
|
- Portable
|
|
- Extensible
|
|
- Client-side
|
|
|
|
## Status
|
|
|
|
Sapling is currently in active development.
|
|
|
|
## Project Layout
|
|
|
|
Sapling currently uses Swift Package Manager as the source-of-truth project layout. Open `Package.swift` in Xcode for app development or run SwiftPM commands from the repository root.
|
|
|
|
```text
|
|
Sapling/
|
|
├── Package.swift
|
|
├── Sources/
|
|
│ ├── SaplingApp/ # SwiftUI app entry point and composition root
|
|
│ ├── SaplingCore/ # Shared domain models and business rules
|
|
│ ├── SaplingWorkspace/ # Workspace and file tree management
|
|
│ ├── SaplingGit/ # Git protocols, macOS provider, embedded stub, mock provider
|
|
│ ├── SaplingEditor/ # Hybrid Markdown editor MVVM surface
|
|
│ ├── SaplingRenderer/ # Markdown rendering abstractions
|
|
│ ├── SaplingStorage/ # Configuration and metadata persistence
|
|
│ └── SaplingUI/ # Shared SwiftUI components
|
|
├── Tests/
|
|
│ └── SaplingCoreTests/
|
|
└── Docs/
|
|
└── Architecture.md
|
|
```
|
|
|
|
## Development
|
|
|
|
Build:
|
|
|
|
```sh
|
|
swift build
|
|
```
|
|
|
|
Test:
|
|
|
|
```sh
|
|
swift test
|
|
```
|
|
|
|
Validate the Milestone 0 development workflow:
|
|
|
|
```sh
|
|
make validate
|
|
```
|
|
|
|
The validation target runs formatting, linting, build, and tests. If `swift-format` is installed, `make format` formats Swift sources in place; otherwise it falls back to the repository lint checks.
|
|
|
|
The app shell can open a local folder as a workspace, scan its filesystem hierarchy, visually distinguish Git repositories as projects, and open Markdown files through reusable document sessions. The architecture is intentionally protocol-first so the macOS implementation can use system Git while future iOS support can use an embedded Git implementation behind the same interfaces.
|
|
|
|
See [Docs/Architecture.md](Docs/Architecture.md) for module responsibilities, architectural decisions, and TODO markers.
|