template / commit
Minor readme update.
README.md | 573 +++++++++++++++++++++++++++++++------------------------------- 1 file changed, 291 insertions(+), 282 deletions(-) diff --git a/README.md b/README.md index e9a8a96..d4ee431 100644 --- a/README.md +++ b/README.md @@ -1,282 +1,291 @@ -# README - -## Name - -template - -## Description - -This CLI creates files and folders with generated templated names, for example `2022-09-26-fhl-2023.md` (generated 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. - -```yaml - - name: daily - description: Creates a MD file in ~/DailyNotes folder in the format YYYY-MM-DD[-vX].md - isdefault: false - isdisabled: false - type: file - runpostscriptonfailure: true - postscripts: - - code . {{ if .FullPath }}"{{.FullPath}}"{{else}}(ls -t | head -n1){{ end }} - namepatterns: - - '{{$version := getVersion}}{{.Year}}-{{.Month}}-{{.Day}}{{if .ProjectName}}-{{.ProjectName | snakecase }}{{end}}{{if (gt $version 1)}}v{{$version}}{{end}}.md' - targetdirectory: ~/DailyNotes - filetemplate: |- - # {{.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: - -```sh -> $ template daily "Cool Thought" -Profile: daily -Project name: Cool Thought -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-20-cool_thought.md -Executing post script: sh -c code . "/Users/fuzzy/DailyNotes/2022-11-20-cool_thought.md" -Post script had no output -``` - -This will cause VSCode to open the `~\DailyNotes` folder as a workspace, and the newly-created file `2022-11-20-cool_thought.md` will be opened as well. - -The above example also uses the [`snakecase`](https://github.com/Masterminds/sprig/blob/master/docs/strings.md#user-content-snakecase) template function. -This is one of the [sprig template functions](https://github.com/Masterminds/sprig/blob/master/docs/index.md) that are supported by template. - -File-based profiles (`type: file`) can accept piped input, and this input will be piped to the created file. -In this instance, the profile's `FileTemplate` field is ignored. -Here's an example of piping the results of `ps` to a file with an auto-generated name: - -```sh -> $ echo "$(ps)" | template log "ps-info" -Profile: log -Project name: ps-info -Loaded config from /Users/fuzzy/.template.yaml -Loaded user config from /Users/fuzzy/.template.user.yaml, combining with global config -Creating file: 2022-12-10-00-05-21-ps-info.log -Executing post script: sh -c code . 2022-12-10-00-05-21-ps-info.log -Post script had no output -``` - -Note that user profiles are combined with the default ones. -This is so you can run `template reset` to reset `~/.template.yaml`, but keep your local profiles/changes as-is. - -## Examples - -### Use `daily` profile to create a new file - -```sh -template daily -``` - -### Use `daily` profile to create a new file with a project name - -```sh -template daily testing -``` - -### Use `daily` profile to create a new file with a project name that contains spaces - -```sh -template daily "this is a test" -``` - -### Use `daily` profile to create a new file with contents piped in from `ps` - -```sh -echo "$(ps)" | template daily -``` - -### Use `work` profile to create a folder with multiple files inside it - -```sh -template work -``` - -### Use `work` profile and project name to create a folder with multiple files inside it - -```sh -template work "fix-bug-123" -``` - -### Use `log` profile to create a `.log` from `stderr` and `stdout` from a `curl` command - -```sh -curl -X GET "https://httpbin.org/delay/3" -H "accept: application/json" 2>&1 | template log -``` - -## Requirements - -The application is a single executable, there are no special requirements. - -Building application requires [go](https://en.wikipedia.org/wiki/Go_(programming_language)). You can download the installer [here](https://go.dev/doc/install). - -The build is managed by [make](https://www.gnu.org/software/make/). - -The default profiles use [Visual Studio Code](https://code.visualstudio.com/) to open the generated files or folders. - -## Installation with Homebrew - -```sh -brew tap PavelSafronov/template https://gitlab.com/PavelSafronov/template.git -brew install template -template reset -``` - -### Uninstall with Homebrew - -```sh -brew uninstall template -brew untap PavelSafronov/template -``` - -## Installation with source - -This repo is available as a go package [`gitlab.com/PavelSafronov/template`](https://pkg.go.dev/gitlab.com/PavelSafronov/template). - -To install, clone the repo and run these commands from the repo directory: -```sh -make install -template reset -``` - -### Uninstall with source - -To uninstall, run this command from the repo directory: -```sh -make uninstall -``` - -## 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. :) - -```powershell -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") -``` - -```bash -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. - -The following command will build the package, test it, and then install it: -```sh -make install -``` - -I use this approach, but that's because I use `template xyz` multiple times a day, and find it helpful to test out a work in progress, and to be using 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 - 1. 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 multiple times, add it to 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 Chocolatey version of app, possibly using [this GoReleaser Chocolatey documentation](https://goreleaser.com/customization/chocolatey/) -2. 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. +# README + +## Name + +template + +## Description + +This CLI creates files and folders with generated templated names, for example `2022-09-26-fhl-2023.md` (generated 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. + +```yaml + - name: daily + description: Creates a MD file in ~/DailyNotes folder in the format YYYY-MM-DD[-vX].md + isdefault: false + isdisabled: false + type: file + runpostscriptonfailure: true + postscripts: + - code . {{ if .FullPath }}"{{.FullPath}}"{{else}}(ls -t | head -n1){{ end }} + namepatterns: + - '{{$version := getVersion}}{{.Year}}-{{.Month}}-{{.Day}}{{if .ProjectName}}-{{.ProjectName | snakecase }}{{end}}{{if (gt $version 1)}}v{{$version}}{{end}}.md' + targetdirectory: ~/DailyNotes + filetemplate: |- + # {{.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: + +```sh +> $ template daily "Cool Thought" +Profile: daily +Project name: Cool Thought +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-20-cool_thought.md +Executing post script: sh -c code . "/Users/fuzzy/DailyNotes/2022-11-20-cool_thought.md" +Post script had no output +``` + +This will cause VSCode to open the `~\DailyNotes` folder as a workspace, and the newly-created file `2022-11-20-cool_thought.md` will be opened as well. + +The above example also uses the [`snakecase`](https://github.com/Masterminds/sprig/blob/master/docs/strings.md#user-content-snakecase) template function. +This is one of the [sprig template functions](https://github.com/Masterminds/sprig/blob/master/docs/index.md) that are supported by template. + +File-based profiles (`type: file`) can accept piped input, and this input will be piped to the created file. +In this instance, the profile's `FileTemplate` field is ignored. +Here's an example of piping the results of `ps` to a file with an auto-generated name: + +```sh +> $ echo "$(ps)" | template log "ps-info" +Profile: log +Project name: ps-info +Loaded config from /Users/fuzzy/.template.yaml +Loaded user config from /Users/fuzzy/.template.user.yaml, combining with global config +Creating file: 2022-12-10-00-05-21-ps-info.log +Executing post script: sh -c code . 2022-12-10-00-05-21-ps-info.log +Post script had no output +``` + +Note that user profiles are combined with the default ones. +This is so you can run `template reset` to reset `~/.template.yaml`, but keep your local profiles/changes as-is. + +## Examples + +### Use `daily` profile to create a new file + +```sh +template daily +``` + +### Use `daily` profile to create a new file with a project name + +```sh +template daily testing +``` + +### Use `daily` profile to create a new file with a project name that contains spaces + +```sh +template daily "this is a test" +``` + +### Use `daily` profile to create a new file with contents piped in from `ps` + +```sh +echo "$(ps)" | template daily +``` + +### Use `work` profile to create a folder with multiple files inside it + +```sh +template work +``` + +### Use `work` profile and project name to create a folder with multiple files inside it + +```sh +template work "fix-bug-123" +``` + +### Use `log` profile to create a `.log` from `stderr` and `stdout` from a `curl` command + +```sh +curl -X GET "https://httpbin.org/delay/3" -H "accept: application/json" 2>&1 | template log +``` + +## Requirements + +The application is a single executable, there are no special requirements. + +Building application requires [go](https://en.wikipedia.org/wiki/Go_(programming_language)). You can download the installer [here](https://go.dev/doc/install). + +The build is managed by [make](https://www.gnu.org/software/make/). + +The default profiles use [Visual Studio Code](https://code.visualstudio.com/) to open the generated files or folders. + +## Installation with Homebrew + +```sh +brew tap PavelSafronov/template https://gitlab.com/PavelSafronov/template.git +brew install template +template reset +``` + +### Uninstall with Homebrew + +```sh +brew uninstall template +brew untap PavelSafronov/template +``` + +## Manual Installation + +1. Navigate to [Releases](https://gitlab.com/PavelSafronov/template/-/releases) +2. Choose the latest release +3. Download the archive file `template_VERSION_OS.tar.gz` +4. From the archive file, extract `template` to a location that's in your PATH + +## Installation with source + +Clone the repo and run these commands from the repo directory: + +```sh +make install +template reset +``` + +### Uninstall with source + +To uninstall, run this command from the repo directory: + +```sh +make uninstall +``` + +## 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. :) + +```powershell +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") +``` + +```bash +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. + +The following command will build the package, test it, and then install it: + +```sh +make install +``` + +I use this approach, but that's because I use `template xyz` multiple times a day, and find it helpful to test out a work in progress, and to be using 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 + 1. 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 multiple times, add it to 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 Chocolatey version of app, possibly using [this GoReleaser Chocolatey documentation](https://goreleaser.com/customization/chocolatey/) +2. 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". +3. Support specifying a template directly to the CLI: `template --file "{{.Year}}-{{.Month}}-{{.Day}}.woot.txt"` will produce file `2023-02-18.woot.txt` + +## 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.