=JumpStart Jumpstart is a gem for quickly creating projects. It does this by running options from a YAML file that you can create, or you can let the gem do it for you. It's dead easy to do. ==Features With jumpstart you can: * Run many terminal commands in a specific order * Create new projects of any type quickly from templates * Create files from three different kinds of templates: * Whole templates. A like for like copy from the template to the new project. * Append templates. The template is appended to a file generated by a terminal command (e.g. rails) * Line templates. The template is inserted into a file generated by a terminal command at a specific line number. * Replace strings in the newly generated project with specified tags (like the project name) * Automatically configure local Nginx and hosts entries for a new project. (I'm using OS X so this is tailored for the Mac.) * Remove unwanted files that may have been created by a terminal command (e.g. rails) == Installation gem install jumpstart Or you can clone this git repo: git://github.com/i0n/jumpstart.git Build jumpstart from the git repo's gemspec: gem build jumpstart.gemspec Install the newly created gem: gem install jumpstart-WHATEVER_THE_CURRENT_VERSION_IS.gem ====NOTE! If you install jumpstart using sudo then you will probably need to run jumpstart with it as well to grant writes to the YAML files in the gem. == Getting Started There are a few ways to use jumpstart. If you have a template and you would like to create a new project with it, pass the jumpstart command two arguments, the first being the new projects name, the second being the existing jumpstart template name. e.g. jumpstart my_new_project my_existing_template If you have already created a template and set it as the default jumpstart template (you can do this in the jumpstart menu), you can create a new project using it by passing just the new projects name to jumpstart. e.g. jumpstart my_new_project If you haven't created any templates yet, or you want to change one of the configuration options (which I'll get to), just call: jumpstart This will launch the jumpstart menu. == Template File Syntax One of the core ideas behind jumpstart is the notion of generating files in a new project automatically from template files. The idea being that you specify a generator of some kind in the jumpstart YAML (the install command), which sets up a generic project (for example rails). Once this has happened the jumpstart template will be parsed for template files to apply to the new project. Anything inside the jumpstart_config directory will not be copied to the project, this is where the templates configuration YAML lives. Everything else is evaluated from the root of the template directory and applied to the new project, again with the projects containing folder treated as the beginning of file paths. So as an example, a jumpstart template called "my_template" containing the path /folder1/folder2/file.txt when parsed would generate the same path in the new project. e.g. my_project/folder1/folder2/file.txt The template files contained in a jumpstart template come in three flavours: * Whole templates. Whole templates are copied to the new project verbatim. Any file that is not recognised as an append or line template is treated as a whole template. * Append templates: _._ or _L._ Append templates append their contents to an existing file. You can get jumpstart to parse a file as an append template by prefixing the file name with _._ So for example say you have a jumpstart template that runs the rails command. After the new rails project has been generated you want jumpstart to append some information to the newly created Gemfile. You could use a whole template and overwrite everything, but this is a bit cumbersome. If things change in Rails (as they do all the time) then you will need to make constant changes to keep the template current. Better to just append what you need to the created file, just like you would do if handling the task manually. To create an append template for the Gemfile, you would create a file called: _._Gemfile There is one more option to bare in mind with append templates. If you specify an L as well, like this: _L._ The last line of the source file (ignoring whitespace) will be removed, and then the append template will be added as normal. Honestly, it's handy. * Line templates: e.g. _123._ Line templates insert their contents into a file at a specified line, pushing existing contents down the page. This is very handy. Say for example that you want to insert some extra configuration information into your new rails projects config/environments/development.rb at line 18. In your jumpstart template you would create a file called config/environments/_18._development.rb If the file you specify doesn't have as many lines as you said it would, whitespace will be added until the specified number is reached. == Task Execution Order Jumpstart tasks are executed in the order that the YAML options below are displayed. == YAML Options ===:install_path: Can be omitted or left blank. If :install_path: is omitted, the new project will be created in whatever directory you are in when you run the command. It is the path where the project directory will be created e.g. :install_path: /Users/i0n/Sites ===:install_command: Can be omitted or left blank. The command that this template will run. The main shell command to create the project. e.g. :install_command: rails ===:install_command_args: Can be omitted or left blank. The arguments for :install_command. Broken into it's own value to allow the project name to be inserted between the two values. e.g. :install_command_args: -d mysql -J -T ===:run_after_install_command: Can be omitted or left blank. Add extra commands that you want to run after the main install command, but before template generation has started. e.g. :run_after_install_command: - rails g controller home - rails g model home ===:remove_files: Can be omitted or left blank. List files that you would like removed from the newly generated project. Paths use the newly created project folder as root. e.g. :remove_files: - /public/index.html - /public/favicon.ico - /public/images/rails.png ===:run_after_jumpstart: Can be omitted or left blank. Add extra commands that you want to run after template generation has completed. e.g. :run_after_jumpstart: - rake db:create - capify! - git init - git add . - git commit -q -v -a -m "Initial commit" ===:replace_strings: Can be omitted or left blank. List files that you would like to perform string substitution on. This can be useful for populating files such as a capistrano deploy.rb file. Paths use the newly created project folder as root. Any key:value pair can be used for substitution, simply add the key name in CAPS to the template file then specify the symbol key and value as in the example. Note! The value of :project_name is hard coded to be the same as the projects name, no matter the value entered in this config file. This helps with capistrano. e.g. :replace_strings: - :target_path: /config/deploy.rb :symbols: :project_name: name_of_my_app :remote_server: thoughtplant - :target_path: /another/config/file.rb :symbols: :project_name: name_of_my_app :womble: uncle_bulgaria ===:local_nginx_conf: Can be omitted or left blank. If you would like jumpstart to configure your local nginx setup specify a path. Handy for rails. e.g. :local_nginx_conf: /usr/local/nginx/conf/nginx.conf ==Example YAML Example 1: Sets up a new Rails project, creating MySQL Dbs and other options. Creates a home controller. Removes superfluous files created by Rails generator. Capifys the project. Creates a git repo and checks everything in to it. Replaces PROJECT_NAME string in capistrano deploy.rb with the name of the new project. Creates and appends to files generated by Rails to get everything ready to go straight away. Configures local Nginx environment. Not bad for one YAML! --- :install_path: /Users/i0n/Sites :install_command: rails :install_command_args: -d mysql -J -T :run_after_install_command: - rails g controller home :remove_files: - /app/views/layouts/application.html.erb - /public/index.html - /public/favicon.ico - /public/images/rails.png :run_after_jumpstart: - rake db:create - capify . - git init - git add . - git commit -q -v -a -m "Initial commit" :replace_strings: - :target_path: /config/deploy.rb :symbols: :project_name: name_of_my_app :remote_server: thoughtplant - :target_path: /config/environments/development.rb :symbols: :project_name: name_of_my_app - :target_path: /config/environments/test.rb :symbols: :project_name: name_of_my_app - :target_path: /config/environments/production.rb :symbols: :project_name: name_of_my_app :local_nginx_conf: /usr/local/nginx/conf/nginx.conf ==Note on Patches/Pull Requests * Fork the project. * Make your feature addition or bug fix. * Add tests for it. This is important so I don't break it in a future version unintentionally. * Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull) * Send me a pull request. Bonus points for topic branches. Copyright Copyright (c) 2010 i0n. See LICENSE for details.