README

Name

template

Description

This CLI creates files and folders with generated templated names, for example 2022-09-26-fhl-2023.md (generator on September 26, 2023, with the project name "fhl-2023"). It's also possible to control the contents of the files: you can specify a template file or an inline template to set the file contents.

This started as a hackathon project that I used to learn Go (golang) and to automate a repetitive task: creation of time-stamped files and folders.

This project is mainly a CLI app written in Go, but it's also a Go module, so it can be used as a dependency. I'm not entirely sure why anyone would want to use this module instead of the CLI, but it's there. Please keep in mind that since my focus is on the CLI, CLI bugs and features will always be prioritized higher than module bugs and features.

Sample tool config

This is one of the profiles that comes with the tool.

    - name: daily
      description: Creates a MD file in ~/DailyNotes folder in the format YYYY-MM-DD[-vX].md
      isdefault: false
      type: file
      path: ~/DailyNotes
      namepatterns:
        - '{{.Year}}-{{.Month}}-{{.Day}}.md'
      runpostscriptonfailure: true
      postscripts:
        - code . {{ if .FullPath }}"{{.FullPath}}"{{else}}(gci . | select -last 1){{ end }}
      file:
        template: |-
            # {{.FileNameWithoutExtension}}

            Today's notes for {{.Year}}-{{.Month}}-{{.Day}}.

            ## Todo

            1. Check email
            2. Check chat
            3. Check calendar
            4. Check yesterday's notes
            5. Have fun!
            6. ADD MORE ITEMS HERE

Using the above configuration:

> template daily
Profile: daily
Project name: 
Loaded config from /Users/fuzzy/.template.yaml
Loaded user config from /Users/fuzzy/.template.user.yaml, combining with global config
Creating file: /Users/fuzzy/DailyNotes/2022-11-07.md
Executing post script: sh -c code . "/Users/fuzzy/DailyNotes/2022-11-07.md"
Post script had no output

This will cause VSCode to open the ~\DailyNotes folder as a workspace, and the newly-created file 2022-09-26.md will be opened as well.

Requirements

The application requires go. You can download the installer here.

The build is managed by make and uses PowerShell Core.

The default profiles use Visual Studio Code.

Package and installation

This repo is available as package gitlab.com/fuzzy-rp/template.

To install, clone the repo and run this command from the repo directory: go install gitlab.com/fuzzy-rp/template@latest

To uninstall, run this command from the repo directory: go clean -i gitlab.com/fuzzy-rp/template...

Running after installation

• template - uses default profile "note" to create a date-stamped MD file in current folder
• template blog OR template --profile blog OR template -p blog - creates a date-stamped MD file in ~/Blog, opens in VSCode
• template daily topic OR template --profile daily --name topic OR template -p daily -n topic - creates a templated date-stamped MD file with topic in its name in ~/DailyNotes, opens in VSCode
• template list - lists all the found profiles
• template get profile2 - lists detailed information about profile profile2
• template reset - resets the configuration to the default config
• Note: this will overwrite whatever config changes you may have made
• Note: the defaults may change from version to version

Creating symbolic links

template currently refers to paths under ~. This is to ensure that it works on all systems.

But I personally keep files in Dropbox, so I usually create symbolic links from (for example) ~/Blog -> ~/Dropbox/Blog. Here are the shell commands that I use, maybe they will be helpful for you. :)

New-Item -ItemType Junction -Path "~\Blog\" -Target (Resolve-Path "~\Dropbox\Blog")
New-Item -ItemType Junction -Path "~\DailyNotes\" -Target (Resolve-Path "~\Dropbox\DailyNotes")
New-Item -ItemType Junction -Path "~\Notes\" -Target (Resolve-Path "~\Dropbox\Notes")
New-Item -ItemType Junction -Path "~\Therapy\" -Target (Resolve-Path "~\Dropbox\Therapy")
New-Item -ItemType Junction -Path "~\Work\" -Target (Resolve-Path "~\Dropbox\Work")

ln -s ~/Dropbox/Blog ~/Blog
ln -s ~/Dropbox/DailyNotes ~/DailyNotes
ln -s ~/Dropbox/Notes ~/Notes
ln -s ~/Dropbox/Therapy ~/Therapy
ln -s ~/Dropbox/Work ~/Work

Dev loop

A simple way to get started is to load this directory in VSCode and debug the project using one of the prepared launch tasks. Use command View: Show Run and Debug to display the launch configs, then pick one and press "Start Debugging" button.

This command will build the package, test it, lint it, and then install it locally: make.

I use this approach, but that's because I typically use template xyz multiple times a day and find it helpful to be testing the latest version.

Support

For anything, open an issue in this repo.

Roadmap

I'm going to use this tool daily to figure out how it can be improved.

While I am the only user, this app will stay at version 0.x.y. At this point, breaking changes may happen.

I'll try to use feature branches, but main will sometimes be in a broken state. Stable versions are tagged after I've had time to test it, so picking up those should be safe.

Once there are enough other users and enough new feature requirements are added, we'll transition to version 1.x.y.

Basic features

Here are the basic features of the CLI that I want to keep:

1. Cross-platform
2. CLI is implemented in Go
3. Fast (under 1s) basic operation of templating file and folder names
4. Postscripts can take longer, as long as the "basic operations" finish quickly enough.

KISS

"Keep It Simple, Stupid"

I want to keep this CLI simple. To that extent, I'm not interested in adding too many features. My main requirement right now is: template blog topic should do the same thing as template --profile blog --name topic.

VSCode and make

Good guidance is invaluable, IMO, so to this extent I am very bullish about adding and using descriptive Makefile and VS Code launch tasks.

Makefile should be used for any build/test/release task. If there is a reason to run a task more than once in the lifetime of a project, add the task to the Makefile with a descriptive name. I don't want to see complicated steps embedded in READMEs or (worse) in code. If the task is important, one that a maintainer/developer/user may want to do, add it to Makefile.

And if the task is more complicated than ~10 lines of pwsh, add a new script under the "./scripts" folder and call the script from Makefile.

Similarly, if there is a good VSCode debug scenario, add a task to launch.json.

Future Features

Here is the future feature list:

1. Publish Homebrew version of app, possibly using this GoReleaser Homebrew documentation
2. Publish Chocolatey version of app, possibly using this GoReleaser Chocolatey documentation
3. Support for passing in a list of template values for custom values in the template. Use might look like this: template work form123 --id=456 --corpOffice=SEA. The passed-in extra values will be placed somewhere inside the template. Some value keys will not be allowed, like "time".

Contributing

Contributions are welcome, but unsolicited PRs are not. If you want to add a particular feature, open an issue first and suggest it. We'll discuss the feature and if I agree that it should be added, you can open a PR.

I don't want to waste my time or your time.

Authors and acknowledgment

Your name will be listed here if you contribute.

License

MIT license.

Project status

This was a hackathon project to learn Go. I'm going to be using this tool and upgrading it as I see fit.