155 lines
3 KiB
Text
155 lines
3 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.
|