bit101 / tinpig

A fast, lightweight command line utility to create projects of any kind from templates.

tinpig Project Creator

tinpig is a simple command line utility for quickly creating projects of any kind. Projects are created from templates which are collections of folders and files. The folders and files can contain special tokens that can be replaced with other values when the project is created. You can use an existing temple as-is, modify a template, or create your own from scratch.

Requirements

You'll need npm and an updated version of nodejs. Your version of nodejs should be 8.5.0 or higher, for the file copying functionality that was introduced at that point.

Installation

npm install -g tinpig

Use

To create a new project, simply type tinpig. This will display a list of available templates for you to choose from.

When you choose a template, tinpig will ask you for a path for your new project. Enter a directory name to create a project with that name in the current directory, or an absolute or relative path to some other location.

If the template includes any replaceable tokens, you will be prompted to provide values for each token. Some tokens may have default values that will be displayed after the name of the token. Press enter to accept the default value, or type an alternate value. Some tokens may be marked as required and others may restrict certain characters to ensure they work correctly as file paths. You'll be notified if your replacement needs correction.

tinpig will then create the project at the specified location, performing all of the token replacment. And you are done, ready to use your new project.

Command line use

If you know the name of the template you want to use and/or the location at which you want to create your project, you can specify these values on the command line.

tinpig --template HTML --path my_project`

or, more concisely:

tinpig -t HTML -p my_project

You can specify one, both, or neither of these values. If you only specify the template you'll be prompted for the path. If you only specify the path, you'll be prompted for a template.

If you specify the path and template, you'll still prompted to enter values for any tokens that may be included in the template.

Also see "External template directories" below for one more command line option.

Configuration

After you install tinpig, run:

tinpig --configure

This will prompt you for a number of values:

• user name
• user email
• custom templates dir
• invalid path characters

The user name and email values can be used by templates to automatically insert your name or email into a project. Feel free to leave these at their default values. You can always edit them later if a project uses them.

By default, tinpig stores its templates in ~/.config/tinpig/templates/. Setting a custom templates dir allows you to store the templates in another location of your choice. More on that later in this doc.

tinpig templates can contain dynamic path and file names. If these are marked as paths, tinpig will make sure that the user enters a path name that will not cause problems. The set of invalid path characters listed here are pretty sensible, but you can customize them if you want.

If you ever want to reset the four config values described above, type:

tinpig reset

This will reset them all to their default values.

All of this data is stored in ~/.config/tinpig/config. You can edit this file manually as well.

Existing content

If the project path you specify already holds a single existing file, you cannot create a project there, obviously.

If the project path is an existing directory, you will be warned of this fact. tinpig will never overwrite or alter existing content in a directory. If the template is attempting to create a file that has the same name as an existing file in that directory, that file will silently fail. Any other non-conflicting files should copy over just fine though. You should be aware of what files the template is creating and know if they will conflict with existing content.

Help

Type tinpig -h or tinpig --help to see a list of options.

Type tinpig -l or tinpig --list to see a list of available templates with descriptions.

Adding new templates

Additional templates will be posted at https://github.com/bit101/tinpig-templates .

Check out or download that repository and copy any templates you want into your local templates directory (~/.config/tinpig/templates) or custom templates dir if you set one. Again, feel free to customize them to make them fit your own use.

Creating new templates

There is a template creation guide on the wiki page. This details the process and all of the elements that go into making a template.

At its simplest, a template is simply a folder containing some files. But there are other features that can make templates more powerful.

If you create a nice template and want to share, submit it as a pull request at https://github.com/bit101/tinpig-templates .

Custom template directories

You can choose to store your templates in a directory other than ~/.config/tinpig/templates. There are two ways to do this.

Changing the path permanently

Run tinpig configure or edit the file ~/.config/tinpig/config and change the templatesDir value to the path you want to store your templates. The next time tinpig starts, it will look there rather than the default location.

Note, if you specify an empty directory, tinpig will copy the default sample templates there the first time it runs.

If you specify a directory that doesn't exist, it will be created and filled with the default sample templates.

Changing the path temporarily

Use the -d or --directory parameter on the command line to point to the directory you want to use. e.g.:

tinpig -d ~/my_templates

You will be asked to choose a template from the ones available in that directory. Note that this directory is only used for this particular run of tinpig. It does not change the values stored in tinpig's configuration.

Note that this method also works if you want to specify a template on the command line. Say ~/my_templates contains a template named GoProject. You could say:

tinpig -d ~/my_templates -t GoProject

You can also list templates from a custom directory:

tinpig -d ~/my_templates -l

This will list all the templates in that location.

tinpig's Issues

.gitignore in webpack project

put eslint as dev dependency

Ignore .DS_Store

I opened my templates directory in finder on my Mac and it created a .DS_Store file.

Afterwards, calling tinpig gives this error:

{ Error: ENOTDIR: not a directory, open '/Users/garthdb/.config/tinpig/templates/.DS_Store/tinpig.json'
  errno: -20,
  code: 'ENOTDIR',
  syscall: 'open',
  path: '/Users/garthdb/.config/tinpig/templates/.DS_Store/tinpig.json' }

I would say you could ignore non-directory paths in the templates directory but that would cause some problems with #38

I'm sure there are other system files that could be ignored.

add a pre message

something that displays right after you choose the template

Allow for a custom templates directory

something like this in config:

"templates_dir": "~/tinpig_templates"

will default to ~/.config/tinpig/templates if not defined here.

validate template name

really only applies on command line --template option. tool should fail immediately with decent error.

Display more items in the list

currently the list shows a few items and scrolls as you move up down. it wraps around. would be nicer if it showed all choices, or at least more. need to look into the options for this.

Get more immediate feedback on invalid template or path

Currently you can enter an invalid path on the command line, then choose a template and token values and only then will you be informed of an unspecified error.

Alternately, you can choose an invalid template name and get all the way to the end and get the same error.

Should recognize the invalid input immediately and surface it right then and there.

Surface errors better

Need more atomic surfacing of errors.

• bad input
• bad path
• anything else that can come up. make an explicit error.

add actual license file to the project

eslint

Create topics (github tags)

Permission error creating project from template

Running tinpig and selecting a template I can't seem to get past Project path:

If I give it a path to an empty directory it responds: >> 'test' already exists.

If I give it a path to create a new directory it responds: >> You don't have access to 'test'.

I tried running it with sudo without success.

have isPath check for other characters that could break path functionality.

https://stackoverflow.com/questions/695438/safe-characters-for-friendly-url
that's more for urls, but a good starting point.

configurable isPath characters.

validate templates on launch

as users add more custom templates, name conflicts could arise. two templates both named HTML for example. tool should detect this when parsing templates at launch, and display a warning.

make a single file option

idea: sometimes you just want to add a single file to a project. maybe a common make file, package.json, .gitignore, license file, etc.

in addition to templates, there could be a files directory. this would just contain a bunch of files.

tinpig -s or tinpig --single would display a list of these files - just the file names. choose one and it's copied to the current directory. no token replacement, no path selection, no manifests.

tinpig -s filename or tinpig --single filename should work as well, with or without the extension. if it finds the file it copies it directly. if not, it opens the list. example:

tinpig -s .gitignore

and you're done.

Allow for default token values

manifest should allow for default values for tokens. this will change the def from:

"tokens": [
  "foo",
  "bar"
]

to:

"tokens": [
  { "token": "foo", "default": "chicken" },
  { "token": "bar", "default": "turkey" }
]

Clean up docs

remove the old todo and project description.

Create a decent readme.md file

Document template format

Create a tinpig templates repo

Have people commit templates via PRs.
Probably grouped by category/language.

add required token

required: true
will not allow no answer
easy to do with inquirer validate function.

replace replace with replace-in-files

replace is out of date. uses out of date and deprecated packages. not updated in years.
replace-in-files was updated 2 days ago.
can accomplish the same functionality.

Sort template list alphabetically

Just realizing that the template list is sorted somewhat randomly. The templates are loaded asynchronously and pushed into the list when they complete loading. Should to a sort on them once they are all loaded.

path to templates and config in window "undefined"

Hi was having a play. The templates and config seemed to be put into an undefined folder. Maybe because I'm on a PC.

My config file is this:
{
"templatesDir": "undefined/.config/tinpig/templates",
"userName": "User Name",
"userEmail": "[email protected]",
"invalidPathChars": "‘“!#$%&+^<=>` "
}

Also tinpig configure just seems to bring up the same template selection screen for me.

Thanks

remove banner except in about

another parameter to specify templates dir

in addition to being able to specify the templates dir in the config, possibility of passing in a templates dir on the command line.

tinpig --templates_dir ~/my_templates

or something.

It would list the templates in that dir. if you added a --template argument, it would only look in that templates dir. user could set up an alias like

alias tinpigpy="tinpig --templates_dir ~/my_python_templates "

Project Description

Elevator pitch. For top of main github page.

Allow for subfolders in templates dir

easy enough to read them.
but should they display as folders? or just a flat list? or maybe just a list with categories:

HTML=====

1. html thing one
2. html thing two
   Python=====
3. python thing one
4. python thing two
   Ruby======
5. ruby thing one

Create a webpack 4 template

Improve token validation

1. look into a user input library to replace readline.
   https://github.com/flatiron/prompt
   https://www.npmjs.com/package/inquirer

2. Use this to better validate things like valid path names, valid identifier names, required input (not empty), etc. Could handle defaults as well maybe.

Create new special tokens

1. TINPIG_USER_NAME
2. TINPIG_USER_EMAIL
3. TINPIG_DATE
4. TINPIG_PROJECT_PATH
5. TINPIG_PROJECT_DIR

User name and email can be defined in the tinpig config file. Can be used directly in templates:

my name is ${TINPIG_USER_NAME}

In this case they will be replaced directly using the value from config if it is defined. Determine some placeholder to use if it is not defined.

They can also be used as defaults in the template manifest:

{
  "name": "USER_NAME",
  "default": "TINPIG_USER_NAME"
}

In this case, the user will be prompted and the config value will be shown as the default:

- USERNAME (John Doe): 

Date, can be formatted using standard timestrf type formats, something like:

date: ${TINPIG_DATE(%d%m%y)}

Not sure how useful this one is. could go on backburner. Would only show project creation date.

path and dir are self-explanatory.

config command:

tinpig configure

prompts for:

• user name
• user email
• template dir
• invalid path chars

uses current values as default.

specify node version in package.json

https://docs.npmjs.com/files/package.json#engines

validation function for project path

1. resolve path
2. if resolve fails, return false.
3. if resolved path already exists, return false.
4. if possible to check for auth to create dir there, check. if fail, return false. (fs.access/fs.accesssync)
5. return true.

Add module to npm

when it's ready.

Look into using Commander

https://www.npmjs.com/package/commander

Make (or get made) a logo

github page and/or wiki

not sure which would be best. probably wiki

figure out best way to do versioning

commander.version(...)
should match release / git tag.

Create one or two non-html/js templates

Rust? Python? Ruby?

Create a "crazy demo" template

For testing and demonstration purposes, shows every possible feature.

• files
• folders
• binary files
• ignored files
• tokenized content
• tokenized file name
• nested tokens (tokenized content in tokenized file name in tokenized directory name)

Create an npm template