fuzzyworld

template / ci-testing / files / README.md

Branch ci-testing · default branch · all branches

README.md

Blame: the commit that last changed each line · file · history

946fecd4 2022-09-25 Pavel Safronov1# README
c1a81484 2022-09-21 Pavel S2
946fecd4 2022-09-25 Pavel Safronov3## Name
4
5template
6
7## Description
8
8c15a714 2022-11-04 Pavel Safronov9This 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").
946fecd4 2022-09-25 Pavel Safronov10It'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.
c1a81484 2022-09-21 Pavel S11
c92ba9aa 2022-11-02 Pavel Safronov12This 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.
0ec42a77 2022-09-26 Pavel Safronov13
7985cf29 2022-11-01 Pavel Safronov14This project is mainly a CLI app written in Go, but it's also a Go module, so it can be used as a dependency.
15I'm not entirely sure why anyone would want to use this module instead of the CLI, but it's there.
16Please 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.
17
0ec42a77 2022-09-26 Pavel Safronov18### Sample tool config
19
20This is one of the profiles that comes with the tool.
21
22```yaml
e86c26ae 2022-11-02 Pavel Safronov23 - name: daily
24 description: Creates a MD file in ~/DailyNotes folder in the format YYYY-MM-DD[-vX].md
25 isdefault: false
ed3d543a 2022-11-20 Pavel Safronov26 isdisabled: false
e86c26ae 2022-11-02 Pavel Safronov27 type: file
28 path: ~/DailyNotes
29 namepatterns:
ed3d543a 2022-11-20 Pavel Safronov30 - '{{$version := getVersion}}{{.Year}}-{{.Month}}-{{.Day}}{{if .ProjectName}}-{{.ProjectName | snakecase }}{{end}}{{if (gt $version 1)}}v{{$version}}{{end}}.md'
e86c26ae 2022-11-02 Pavel Safronov31 runpostscriptonfailure: true
32 postscripts:
ed3d543a 2022-11-20 Pavel Safronov33 - code . {{ if .FullPath }}"{{.FullPath}}"{{else}}(ls -t | head -n1){{ end }}
e86c26ae 2022-11-02 Pavel Safronov34 file:
dd789946 2022-10-24 Pavel Safronov35 template: |-
e86c26ae 2022-11-02 Pavel Safronov36 # {{.FileNameWithoutExtension}}
dd789946 2022-10-24 Pavel Safronov37
e86c26ae 2022-11-02 Pavel Safronov38 Today's notes for {{.Year}}-{{.Month}}-{{.Day}}.
dd789946 2022-10-24 Pavel Safronov39
40 ## Todo
41
42 1. Check email
43 2. Check chat
44 3. Check calendar
45 4. Check yesterday's notes
46 5. Have fun!
47 6. ADD MORE ITEMS HERE
0ec42a77 2022-09-26 Pavel Safronov48```
49
50Using the above configuration:
52e9ad7c 2022-11-08 Pavel Safronov51```sh
ed3d543a 2022-11-20 Pavel Safronov52> $ template daily "Cool Thought"
0ec42a77 2022-09-26 Pavel Safronov53Profile: daily
ed3d543a 2022-11-20 Pavel Safronov54Project name: Cool Thought
e86c26ae 2022-11-02 Pavel Safronov55Loaded config from /Users/fuzzy/.template.yaml
52e9ad7c 2022-11-08 Pavel Safronov56Loaded user config from /Users/fuzzy/.template.user.yaml, combining with global config
ed3d543a 2022-11-20 Pavel Safronov57Creating file: /Users/fuzzy/DailyNotes/2022-11-20-cool_thought.md
58Executing post script: sh -c code . "/Users/fuzzy/DailyNotes/2022-11-20-cool_thought.md"
e86c26ae 2022-11-02 Pavel Safronov59Post script had no output
0ec42a77 2022-09-26 Pavel Safronov60```
61
ed3d543a 2022-11-20 Pavel Safronov62This 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.
63
64The above example also uses the [`snakecase`](https://github.com/Masterminds/sprig/blob/master/docs/strings.md#user-content-snakecase) template function.
65This is one of the [sprig template functions](https://github.com/Masterminds/sprig/blob/master/docs/index.md) that are exposed by template.
0ec42a77 2022-09-26 Pavel Safronov66
0caca641 2022-09-26 Pavel Safronov67## Requirements
68
69The application requires [go](https://en.wikipedia.org/wiki/Go_(programming_language)). You can download the installer [here](https://go.dev/doc/install).
70
52e9ad7c 2022-11-08 Pavel Safronov71The build is managed by [make](https://www.gnu.org/software/make/).
312f37c3 2022-10-06 Pavel Safronov72
52e9ad7c 2022-11-08 Pavel Safronov73The default profiles use [Visual Studio Code](https://code.visualstudio.com/).
0caca641 2022-09-26 Pavel Safronov74
b2333ccf 2022-10-26 Pavel Safronov75## Package and installation
4a7361b0 2022-09-21 Pavel Safronov76
8179bb1c 2022-10-26 Pavel Safronov77This repo is available as package [`gitlab.com/fuzzy-rp/template`](https://pkg.go.dev/gitlab.com/fuzzy-rp/template).
4a7361b0 2022-09-21 Pavel Safronov78
8179bb1c 2022-10-26 Pavel Safronov79To install, clone the repo and run this command from the repo directory:
80`go install gitlab.com/fuzzy-rp/template@latest`
f819f801 2022-09-21 Pavel Safronov81
8179bb1c 2022-10-26 Pavel Safronov82To uninstall, run this command from the repo directory:
b67e39c6 2022-10-26 Pavel Safronov83`go clean -i gitlab.com/fuzzy-rp/template...`
f819f801 2022-09-21 Pavel Safronov84
946fecd4 2022-09-25 Pavel Safronov85### Running after installation
f819f801 2022-09-21 Pavel Safronov86
946fecd4 2022-09-25 Pavel Safronov87- `template` - uses default profile "note" to create a date-stamped MD file in current folder
dd789946 2022-10-24 Pavel Safronov88- `template blog` OR `template --profile blog` OR `template -p blog` - creates a date-stamped MD file in ~/Blog, opens in VSCode
89- `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
b2333ccf 2022-10-26 Pavel Safronov90- `template list` - lists all the found profiles
91- `template get profile2` - lists detailed information about profile `profile2`
92- `template reset` - resets the configuration to the default config
93 - *Note*: this will overwrite whatever config changes you may have made
94 - *Note*: the defaults may change from version to version
dd789946 2022-10-24 Pavel Safronov95
96### Creating symbolic links
97
98template currently refers to paths under `~`. This is to ensure that it works on all systems.
99
52e9ad7c 2022-11-08 Pavel Safronov100But 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. :)
dd789946 2022-10-24 Pavel Safronov101
102```powershell
103New-Item -ItemType Junction -Path "~\Blog\" -Target (Resolve-Path "~\Dropbox\Blog")
104New-Item -ItemType Junction -Path "~\DailyNotes\" -Target (Resolve-Path "~\Dropbox\DailyNotes")
105New-Item -ItemType Junction -Path "~\Notes\" -Target (Resolve-Path "~\Dropbox\Notes")
106New-Item -ItemType Junction -Path "~\Therapy\" -Target (Resolve-Path "~\Dropbox\Therapy")
107New-Item -ItemType Junction -Path "~\Work\" -Target (Resolve-Path "~\Dropbox\Work")
108```
f819f801 2022-09-21 Pavel Safronov109
d1ab6234 2022-10-25 Pavel Safronov110```bash
111ln -s ~/Dropbox/Blog ~/Blog
112ln -s ~/Dropbox/DailyNotes ~/DailyNotes
113ln -s ~/Dropbox/Notes ~/Notes
114ln -s ~/Dropbox/Therapy ~/Therapy
115ln -s ~/Dropbox/Work ~/Work
116```
117
b2333ccf 2022-10-26 Pavel Safronov118## Dev loop
4a7361b0 2022-09-21 Pavel Safronov119
8179bb1c 2022-10-26 Pavel Safronov120A 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.
c1a81484 2022-09-21 Pavel S121
c92ba9aa 2022-11-02 Pavel Safronov122The following command will build the package, test it, and then install it. I use this approach, but that's because I use `template xyz` multiple times a day, and find it helpful to be using the latest version.
123
c1a81484 2022-09-21 Pavel S124## Support
f819f801 2022-09-21 Pavel Safronov125
946fecd4 2022-09-25 Pavel Safronov126For anything, open an issue in this repo.
c1a81484 2022-09-21 Pavel S127
128## Roadmap
f819f801 2022-09-21 Pavel Safronov129
946fecd4 2022-09-25 Pavel Safronov130I'm going to use this tool daily to figure out how it can be improved.
29b941bc 2022-09-30 Pavel Safronov131
a5ad914b 2022-10-30 Pavel Safronov132While I am the only user, this app will stay at version `0.x.y`.
133At this point, breaking changes may happen.
134
2d11cb62 2022-11-16 Pavel Safronov135I'll try to use feature branches, but main will sometimes be in a broken state.
136Stable versions are tagged after I've had time to test it, so picking up those should be safe.
137
a5ad914b 2022-10-30 Pavel Safronov138Once there are enough other users and enough new feature requirements are added, we'll transition to version `1.x.y`.
139
29b941bc 2022-09-30 Pavel Safronov140### Basic features
141
142Here are the basic features of the CLI that I want to keep:
143
1441. Cross-platform
1452. CLI is implemented in Go
1463. Fast (under 1s) basic operation of templating file and folder names
dd789946 2022-10-24 Pavel Safronov147 1. Postscripts can take longer, as long as the "basic operations" finish quickly enough.
29b941bc 2022-09-30 Pavel Safronov148
149### KISS
150
151"Keep It Simple, Stupid"
152
312f37c3 2022-10-06 Pavel Safronov153I 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`.
29b941bc 2022-09-30 Pavel Safronov154
1993289f 2022-11-16 Pavel Safronov155### VSCode and make
156
157Good guidance is invaluable, IMO, so to this extent I am very bullish about adding and using descriptive Makefile and VS Code launch tasks.
158
159Makefile 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.
160I 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.
161
162Similarly, if there is a good VSCode debug scenario, add a task to launch.json.
163
29b941bc 2022-09-30 Pavel Safronov164### Future Features
165
166Here is the future feature list:
3f44cff4 2022-09-26 Pavel Safronov167
a2aa5f42 2022-11-16 Pavel Safronov1681. Publish Homebrew version of app, possibly using [this GoReleaser Homebrew documentation](https://goreleaser.com/customization/homebrew/)
1692. Publish Chocolatey version of app, possibly using [this GoReleaser Chocolatey documentation](https://goreleaser.com/customization/chocolatey/)
1703. 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".
c1a81484 2022-09-21 Pavel S171
172## Contributing
f819f801 2022-09-21 Pavel Safronov173
2d11cb62 2022-11-16 Pavel Safronov174Contributions are welcome, but unsolicited PRs are not.
175If you want to add a particular feature, open an issue first and suggest it.
176We'll discuss the feature and if I agree that it should be added, you can open a PR.
177
178I don't want to waste my time or your time.
c1a81484 2022-09-21 Pavel S179
180## Authors and acknowledgment
f819f801 2022-09-21 Pavel Safronov181
946fecd4 2022-09-25 Pavel Safronov182Your name will be listed here if you contribute.
c1a81484 2022-09-21 Pavel S183
184## License
f819f801 2022-09-21 Pavel Safronov185
946fecd4 2022-09-25 Pavel Safronov186MIT license.
c1a81484 2022-09-21 Pavel S187
188## Project status
f819f801 2022-09-21 Pavel Safronov189
946fecd4 2022-09-25 Pavel Safronov190This was a hackathon project to learn Go.
191I'm going to be using this tool and upgrading it as I see fit.