README.md

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

`946fecd4` 2022-09-25 Pavel Safronov	1	# README
`c1a81484` 2022-09-21 Pavel S	2
`946fecd4` 2022-09-25 Pavel Safronov	3	## Name
	4
	5	template
	6
	7	## Description
	8
`8c15a714` 2022-11-04 Pavel Safronov	9	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").
`946fecd4` 2022-09-25 Pavel Safronov	10	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.
`c1a81484` 2022-09-21 Pavel S	11
`c92ba9aa` 2022-11-02 Pavel Safronov	12	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.
`0ec42a77` 2022-09-26 Pavel Safronov	13
`7985cf29` 2022-11-01 Pavel Safronov	14	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.
	15	I'm not entirely sure why anyone would want to use this module instead of the CLI, but it's there.
	16	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.
	17
`0ec42a77` 2022-09-26 Pavel Safronov	18	### Sample tool config
	19
	20	This is one of the profiles that comes with the tool.
	21
	22	```yaml
`e86c26ae` 2022-11-02 Pavel Safronov	23	- name: daily
	24	description: Creates a MD file in ~/DailyNotes folder in the format YYYY-MM-DD[-vX].md
	25	isdefault: false
	26	type: file
	27	path: ~/DailyNotes
	28	namepatterns:
	29	- '{{.Year}}-{{.Month}}-{{.Day}}.md'
	30	runpostscriptonfailure: true
	31	postscripts:
	32	- code . {{ if .FullPath }}"{{.FullPath}}"{{else}}(gci . \| select -last 1){{ end }}
	33	file:
`dd789946` 2022-10-24 Pavel Safronov	34	template: \|-
`e86c26ae` 2022-11-02 Pavel Safronov	35	# {{.FileNameWithoutExtension}}
`dd789946` 2022-10-24 Pavel Safronov	36
`e86c26ae` 2022-11-02 Pavel Safronov	37	Today's notes for {{.Year}}-{{.Month}}-{{.Day}}.
`dd789946` 2022-10-24 Pavel Safronov	38
	39	## Todo
	40
	41	1. Check email
	42	2. Check chat
	43	3. Check calendar
	44	4. Check yesterday's notes
	45	5. Have fun!
	46	6. ADD MORE ITEMS HERE
`0ec42a77` 2022-09-26 Pavel Safronov	47	```
	48
	49	Using the above configuration:
`fe86bedc` 2022-11-17 Pavel Safronov	50
`52e9ad7c` 2022-11-08 Pavel Safronov	51	```sh
	52	> template daily
`0ec42a77` 2022-09-26 Pavel Safronov	53	Profile: daily
`e86c26ae` 2022-11-02 Pavel Safronov	54	Project name:
	55	Loaded config from /Users/fuzzy/.template.yaml
`52e9ad7c` 2022-11-08 Pavel Safronov	56	Loaded user config from /Users/fuzzy/.template.user.yaml, combining with global config
	57	Creating file: /Users/fuzzy/DailyNotes/2022-11-07.md
	58	Executing post script: sh -c code . "/Users/fuzzy/DailyNotes/2022-11-07.md"
`e86c26ae` 2022-11-02 Pavel Safronov	59	Post script had no output
`0ec42a77` 2022-09-26 Pavel Safronov	60	```
	61
`dd789946` 2022-10-24 Pavel Safronov	62	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.
`0ec42a77` 2022-09-26 Pavel Safronov	63
`0caca641` 2022-09-26 Pavel Safronov	64	## Requirements
	65
	66	The application requires [go](https://en.wikipedia.org/wiki/Go_(programming_language)). You can download the installer [here](https://go.dev/doc/install).
	67
`fe86bedc` 2022-11-17 Pavel Safronov	68	The build is managed by [make](https://www.gnu.org/software/make/) and uses [PowerShell Core](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell).
`312f37c3` 2022-10-06 Pavel Safronov	69
`52e9ad7c` 2022-11-08 Pavel Safronov	70	The default profiles use [Visual Studio Code](https://code.visualstudio.com/).
`0caca641` 2022-09-26 Pavel Safronov	71
`b2333ccf` 2022-10-26 Pavel Safronov	72	## Package and installation
`4a7361b0` 2022-09-21 Pavel Safronov	73
`8179bb1c` 2022-10-26 Pavel Safronov	74	This repo is available as package [`gitlab.com/fuzzy-rp/template`](https://pkg.go.dev/gitlab.com/fuzzy-rp/template).
`4a7361b0` 2022-09-21 Pavel Safronov	75
`8179bb1c` 2022-10-26 Pavel Safronov	76	To install, clone the repo and run this command from the repo directory:
	77	`go install gitlab.com/fuzzy-rp/template@latest`
`f819f801` 2022-09-21 Pavel Safronov	78
`8179bb1c` 2022-10-26 Pavel Safronov	79	To uninstall, run this command from the repo directory:
`b67e39c6` 2022-10-26 Pavel Safronov	80	`go clean -i gitlab.com/fuzzy-rp/template...`
`f819f801` 2022-09-21 Pavel Safronov	81
`946fecd4` 2022-09-25 Pavel Safronov	82	### Running after installation
`f819f801` 2022-09-21 Pavel Safronov	83
`946fecd4` 2022-09-25 Pavel Safronov	84	- `template` - uses default profile "note" to create a date-stamped MD file in current folder
`dd789946` 2022-10-24 Pavel Safronov	85	- `template blog` OR `template --profile blog` OR `template -p blog` - creates a date-stamped MD file in ~/Blog, opens in VSCode
	86	- `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 Safronov	87	- `template list` - lists all the found profiles
	88	- `template get profile2` - lists detailed information about profile `profile2`
	89	- `template reset` - resets the configuration to the default config
	90	- Note: this will overwrite whatever config changes you may have made
	91	- Note: the defaults may change from version to version
`dd789946` 2022-10-24 Pavel Safronov	92
	93	### Creating symbolic links
	94
	95	template currently refers to paths under `~`. This is to ensure that it works on all systems.
	96
`52e9ad7c` 2022-11-08 Pavel Safronov	97	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. :)
`dd789946` 2022-10-24 Pavel Safronov	98
	99	```powershell
	100	New-Item -ItemType Junction -Path "~\Blog\" -Target (Resolve-Path "~\Dropbox\Blog")
	101	New-Item -ItemType Junction -Path "~\DailyNotes\" -Target (Resolve-Path "~\Dropbox\DailyNotes")
	102	New-Item -ItemType Junction -Path "~\Notes\" -Target (Resolve-Path "~\Dropbox\Notes")
	103	New-Item -ItemType Junction -Path "~\Therapy\" -Target (Resolve-Path "~\Dropbox\Therapy")
	104	New-Item -ItemType Junction -Path "~\Work\" -Target (Resolve-Path "~\Dropbox\Work")
	105	```
`f819f801` 2022-09-21 Pavel Safronov	106
`d1ab6234` 2022-10-25 Pavel Safronov	107	```bash
	108	ln -s ~/Dropbox/Blog ~/Blog
	109	ln -s ~/Dropbox/DailyNotes ~/DailyNotes
	110	ln -s ~/Dropbox/Notes ~/Notes
	111	ln -s ~/Dropbox/Therapy ~/Therapy
	112	ln -s ~/Dropbox/Work ~/Work
	113	```
	114
`b2333ccf` 2022-10-26 Pavel Safronov	115	## Dev loop
`4a7361b0` 2022-09-21 Pavel Safronov	116
`8179bb1c` 2022-10-26 Pavel Safronov	117	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.
`c1a81484` 2022-09-21 Pavel S	118
`fe86bedc` 2022-11-17 Pavel Safronov	119	This command will build the package, test it, lint it, and then install it locally: `make`.
	120
	121	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.
`c92ba9aa` 2022-11-02 Pavel Safronov	122
`c1a81484` 2022-09-21 Pavel S	123	## Support
`f819f801` 2022-09-21 Pavel Safronov	124
`946fecd4` 2022-09-25 Pavel Safronov	125	For anything, open an issue in this repo.
`c1a81484` 2022-09-21 Pavel S	126
	127	## Roadmap
`f819f801` 2022-09-21 Pavel Safronov	128
`946fecd4` 2022-09-25 Pavel Safronov	129	I'm going to use this tool daily to figure out how it can be improved.
`29b941bc` 2022-09-30 Pavel Safronov	130
`a5ad914b` 2022-10-30 Pavel Safronov	131	While I am the only user, this app will stay at version `0.x.y`.
	132	At this point, breaking changes may happen.
	133
`2d11cb62` 2022-11-16 Pavel Safronov	134	I'll try to use feature branches, but main will sometimes be in a broken state.
	135	Stable versions are tagged after I've had time to test it, so picking up those should be safe.
	136
`a5ad914b` 2022-10-30 Pavel Safronov	137	Once there are enough other users and enough new feature requirements are added, we'll transition to version `1.x.y`.
	138
`29b941bc` 2022-09-30 Pavel Safronov	139	### Basic features
	140
	141	Here are the basic features of the CLI that I want to keep:
	142
	143	1. Cross-platform
	144	2. CLI is implemented in Go
	145	3. Fast (under 1s) basic operation of templating file and folder names
`dd789946` 2022-10-24 Pavel Safronov	146	1. Postscripts can take longer, as long as the "basic operations" finish quickly enough.
`29b941bc` 2022-09-30 Pavel Safronov	147
	148	### KISS
	149
	150	"Keep It Simple, Stupid"
	151
`312f37c3` 2022-10-06 Pavel Safronov	152	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`.
`29b941bc` 2022-09-30 Pavel Safronov	153
`1993289f` 2022-11-16 Pavel Safronov	154	### VSCode and make
	155
	156	Good guidance is invaluable, IMO, so to this extent I am very bullish about adding and using descriptive Makefile and VS Code launch tasks.
	157
	158	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.
	159	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.
	160
`fe86bedc` 2022-11-17 Pavel Safronov	161	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.
	162
`1993289f` 2022-11-16 Pavel Safronov	163	Similarly, if there is a good VSCode debug scenario, add a task to launch.json.
	164
`29b941bc` 2022-09-30 Pavel Safronov	165	### Future Features
	166
	167	Here is the future feature list:
`3f44cff4` 2022-09-26 Pavel Safronov	168
`a2aa5f42` 2022-11-16 Pavel Safronov	169	1. Publish Homebrew version of app, possibly using [this GoReleaser Homebrew documentation](https://goreleaser.com/customization/homebrew/)
	170	2. Publish Chocolatey version of app, possibly using [this GoReleaser Chocolatey documentation](https://goreleaser.com/customization/chocolatey/)
	171	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".
`c1a81484` 2022-09-21 Pavel S	172
	173	## Contributing
`f819f801` 2022-09-21 Pavel Safronov	174
`2d11cb62` 2022-11-16 Pavel Safronov	175	Contributions are welcome, but unsolicited PRs are not.
	176	If you want to add a particular feature, open an issue first and suggest it.
	177	We'll discuss the feature and if I agree that it should be added, you can open a PR.
	178
	179	I don't want to waste my time or your time.
`c1a81484` 2022-09-21 Pavel S	180
	181	## Authors and acknowledgment
`f819f801` 2022-09-21 Pavel Safronov	182
`946fecd4` 2022-09-25 Pavel Safronov	183	Your name will be listed here if you contribute.
`c1a81484` 2022-09-21 Pavel S	184
	185	## License
`f819f801` 2022-09-21 Pavel Safronov	186
`946fecd4` 2022-09-25 Pavel Safronov	187	MIT license.
`c1a81484` 2022-09-21 Pavel S	188
	189	## Project status
`f819f801` 2022-09-21 Pavel Safronov	190
`946fecd4` 2022-09-25 Pavel Safronov	191	This was a hackathon project to learn Go.
	192	I'm going to be using this tool and upgrading it as I see fit.