FLO/dirmd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

simplify readme and make a force flag for local overrides

Browse Source
This commit is contained in:
Bartal Laearsson
2026-08-05 10:30:20 +01:00
parent 54f1c2e355
commit bccf9bf198
3 changed files with 72 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+54 -10
View File
@@ -9,7 +9,9 @@ Generate markdown documentation from directory structure.
- Full file contents with syntax-highlighted code blocks
- Filters dotfiles, binaries, and blacklisted extensions
- Append mode for single files or directories
- Force overwrite of existing output files
- Configurable depth, file size limits, ignore patterns
- Optional upload to Proton Drive after generating output
## Build
@@ -19,36 +21,78 @@ Generate markdown documentation from directory structure.
# Create new documentation
dirmd -o output.md ~/repos/myproject
# Overwrite existing output file
dirmd -o output.md ~/repos/myproject -f
# Append a single file
dirmd -a -i README.md -o existing.md
# Append another directory
dirmd -a ~/repos/anotherproject -o existing.md
# Generate and upload to Proton Drive (default: /my-files/md/<filename>)
dirmd -o output.md ~/repos/myproject --proton-drive
# Generate and upload to a specific remote path
dirmd -o output.md ~/repos/myproject --proton-drive --drive-path /my-files/docs/api.md
## Flags
| Flag | Description | Default |
|------|-------------|---------|
| `-o`, `--output` | Output markdown file path (required) | |
| `-a`, `--append` | Append to existing output file | false |
| `-f`, `--force` | Overwrite existing output file (non-append mode) | false |
| `-i`, `--input-file` | Single file input (append mode only) | |
| `--max-size` | Max file size in bytes | 524288 |
| `--max-depth` | Max directory recursion depth | 20 |
| `--ignore` | Additional ignore patterns (glob) | |
| `--extensions` | Additional file extensions to skip | |
| `--proton-drive` | Upload output to Proton Drive after writing locally | false |
| `--drive-path` | Full remote path on Proton Drive (e.g. /my-files/md/report.md) | /my-files/md/&lt;filename&gt; |
## Proton Drive Integration
dirmd can optionally upload the generated markdown file to Proton Drive using the [Proton Drive CLI](https://proton.me/support/drive-cli). The upload is performed only when `--proton-drive` is passed. Without it, dirmd behaves exactly as before — no Proton Drive dependency is required.
### Prerequisites
1. Install the Proton Drive CLI — see the [official guide](https://proton.me/support/drive-cli) for download and installation instructions.
2. Authenticate by running `proton-drive auth login`.
3. Ensure `proton-drive` is in your `PATH`.
If the CLI is not installed or you are not logged in, dirmd will report the error to stderr and exit with a non-zero code. The local markdown file is still written successfully before the upload is attempted.
### Upload Behavior
- Default remote path: `/my-files/md/<filename>` where `<filename>` is the basename of the local output file.
- Override with `--drive-path /my-files/custom/report.md` (full path including filename).
- Existing remote files are overwritten (`--conflict-strategy replace`).
- The local markdown file is always written before the upload is attempted.
For full documentation on the Proton Drive CLI, including installation, authentication, and troubleshooting, refer to the [official Proton Drive CLI support page](https://proton.me/support/drive-cli).
## Examples
# Custom depth and size limit
dirmd -o output.md ~/repos/project --max-depth 5 --max-size 262144
# Ignore specific directories
dirmd -o output.md ~/repos/project --ignore __pycache__ --ignore .venv
# Skip additional file extensions
dirmd -o output.md ~/repos/project --extensions .log --extensions .tmp
# Generate, then upload to default remote location
dirmd -o docs.md ~/repos/project --proton-drive
# Generate, then upload to a custom remote location
dirmd -o docs.md ~/repos/project --proton-drive --drive-path /my-files/projects/docs.md
# Overwrite existing local file and upload to Drive
dirmd -o docs.md ~/repos/project -f --proton-drive
## Output Format
Produces markdown with:
@@ -61,22 +105,22 @@ Produces markdown with:
Example output structure:
# /home/user/repos/myproject
## Directory Tree
myproject/
├── cmd/
│ └── main.go
└── internal/
└── config.go
## Contents
### ./cmd/main.go
```go
package main
func main() {}
```
cmd/root.go
+12 -6
View File
@@ -19,7 +19,7 @@ var (
Short: "Generate markdown documentation from directory structure",
Long: `dirmd walks a directory and generates a markdown file with:
- Directory tree structure
- Directory tree structure
- All readable text files with their contents
Examples:
@@ -27,12 +27,15 @@ Examples:
# Create new documentation
dirmd -o output.md ~/repos/myproject
# Append a single file
# Append a single file
dirmd -a -i README.md -o existing.md
# Append another directory
dirmd -a -o existing.md ~/repos/anotherproject
# Overwrite existing local file
dirmd -o output.md ~/repos/myproject -f
# Generate and upload to Proton Drive (default remote path /my-files/md/<filename>)
dirmd -o output.md ~/repos/myproject --proton-drive
@@ -43,6 +46,7 @@ Examples:
outputPath string
appendMode bool
force bool
singleFile string
maxSize int64
maxDepth int
@@ -61,6 +65,7 @@ func Execute() {
func init() {
rootCmd.PersistentFlags().StringVarP(&outputPath, "output", "o", "", "output markdown file path (required)")
rootCmd.Flags().BoolVarP(&appendMode, "append", "a", false, "append to existing output file")
rootCmd.Flags().BoolVarP(&force, "force", "f", false, "overwrite existing output file (non-append mode)")
rootCmd.Flags().StringVarP(&singleFile, "input-file", "i", "", "single file input (append mode only)")
rootCmd.Flags().Int64Var(&maxSize, "max-size", config.DefaultMaxSize, "max file size in bytes")
rootCmd.Flags().IntVar(&maxDepth, "max-depth", config.DefaultMaxDepth, "max directory recursion depth")
@@ -80,6 +85,7 @@ func run(cmd *cobra.Command, args []string) error {
cfg := &config.Config{
OutputPath: outputPath,
AppendMode: appendMode,
Force: force,
MaxSize: maxSize,
MaxDepth: maxDepth,
Ignores: append(config.DefaultIgnores, ignorePatterns...),
@@ -107,10 +113,10 @@ func run(cmd *cobra.Command, args []string) error {
}
cfg.AbsRoot = abs
// Non-append mode: output must not exist
// Non-append mode: check for existing output file
if !appendMode {
if _, err := os.Stat(outputPath); err == nil {
return fmt.Errorf("output file %s already exists (use -a to append)", outputPath)
if _, err := os.Stat(outputPath); err == nil && !force {
return fmt.Errorf("output file %s already exists (use -f to overwrite or -a to append)", outputPath)
}
}
@@ -132,7 +138,7 @@ func run(cmd *cobra.Command, args []string) error {
if protonDrive {
remotePath := drivePath
if remotePath == "" {
remotePath = "/my-files/md/" + filepath.Base(outputPath)
remotePath = "/my/files/md/" + filepath.Base(outputPath)
}
if err := drive.CheckAuth(); err != nil {
internal/config/config.go
+6 -2
View File
@@ -56,6 +56,7 @@ type Config struct {
InputPath string
OutputPath string
AppendMode bool
Force bool
SingleFile bool
MaxSize int64
MaxDepth int
@@ -79,6 +80,7 @@ func Parse() (*Config, error) {
input string
output string
appendMd bool
force bool
maxSize int64
maxDepth int
ignores stringSlice
@@ -91,6 +93,7 @@ func Parse() (*Config, error) {
flag.StringVar(&input, "i", "", "single file input (append mode only)")
flag.StringVar(&output, "o", "", "output markdown file path (required)")
flag.BoolVar(&appendMd, "a", false, "append to existing output file")
flag.BoolVar(&force, "f", false, "overwrite existing output file (non-append mode)")
flag.Int64Var(&maxSize, "max-size", DefaultMaxSize, "max file size in bytes")
flag.IntVar(&maxDepth, "max-depth", DefaultMaxDepth, "max directory recursion depth")
flag.Var(&ignores, "ignore", "additional ignore patterns (glob, repeatable)")
@@ -118,6 +121,7 @@ func Parse() (*Config, error) {
cfg := &Config{
OutputPath: output,
AppendMode: appendMd,
Force: force,
MaxSize: maxSize,
MaxDepth: maxDepth,
Ignores: append(DefaultIgnores, ignores...),
@@ -147,8 +151,8 @@ func Parse() (*Config, error) {
cfg.AbsRoot = abs
if !appendMd {
if _, err := os.Stat(output); err == nil {
return nil, fmt.Errorf("output file %s already exists (use -a to append)", output)
if _, err := os.Stat(output); err == nil && !force {
return nil, fmt.Errorf("output file %s already exists (use -f to overwrite or -a to append)", output)
}
}