From bc87c8523df43030ec1c265b6a9b531bb287ce7c Mon Sep 17 00:00:00 2001 From: Jan Pietrzyk Date: Tue, 30 Aug 2016 14:11:29 +0200 Subject: [PATCH 1/9] fix build dependency on local development --- actions/build.sh | 3 --- 1 file changed, 3 deletions(-) diff --git a/actions/build.sh b/actions/build.sh index 1b964b1..4717512 100644 --- a/actions/build.sh +++ b/actions/build.sh @@ -17,7 +17,4 @@ chmod +x build/psh56.phar php box.phar build mv psh.phar build/psh.phar chmod +x build/psh.phar - -cp build/psh56.phar ../b2b/psh.phar - rm -R build/php56 \ No newline at end of file From 6b752fbbb0c3661d969df4487e067ec350e700bf Mon Sep 17 00:00:00 2001 From: Jan Pietrzyk Date: Tue, 30 Aug 2016 14:12:57 +0200 Subject: [PATCH 2/9] add MIT license and configure executable --- LICENSE | 21 +++++++++++++++++++++ composer.json | 3 ++- 2 files changed, 23 insertions(+), 1 deletion(-) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..22f245b --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2016 Shopware AG + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/composer.json b/composer.json index b824d2a..5bad753 100644 --- a/composer.json +++ b/composer.json @@ -2,6 +2,7 @@ "name": "shopware/psh", "description": "A build tool written in PHP utilizing sh scripts", "type": "application", + "bin": ["psh"], "autoload": { "psr-4": { "Shopware\\Psh\\": "src" @@ -25,7 +26,7 @@ "phpunit/phpunit": "^5.4", "janpiet/php-version-transpiler": "dev-master" }, - "license": "proprietary", + "license": "MIT", "authors": [ { "name": "Jan Pietrzyk", From 14dd9c917c2bba45af21b71e6886a4e58b4ff73f Mon Sep 17 00:00:00 2001 From: Jan Pietrzyk Date: Tue, 30 Aug 2016 14:13:23 +0200 Subject: [PATCH 3/9] add test to secure minimum configuration --- README.md | 235 +++++++++++++----- tests/Acceptance/ApplicationTest.php | 37 +-- tests/Acceptance/MinApplicationTest.php | 20 ++ tests/Acceptance/MockWriter.php | 32 +++ tests/Acceptance/_minApp/.psh.yml | 6 + .../Acceptance/_minApp/my/sh/scripts/test.sh | 3 + 6 files changed, 243 insertions(+), 90 deletions(-) create mode 100644 tests/Acceptance/MinApplicationTest.php create mode 100644 tests/Acceptance/MockWriter.php create mode 100644 tests/Acceptance/_minApp/.psh.yml create mode 100644 tests/Acceptance/_minApp/my/sh/scripts/test.sh diff --git a/README.md b/README.md index c3b66d7..404bdee 100644 --- a/README.md +++ b/README.md @@ -1,97 +1,216 @@ PSH - PHP shell helper ==================== -A Tool to execute *.sh scripts through php, including a templating language and environment settings. +Introduction +------------ -## Contained actions +A Tool to execute shell scripts through php, including a small templating engine and environment settings. It can be used +as an easy way to create adaptable dev-ops scripts from existing or newly written shell scripts. You do not have to learn +a new - and in most cases much more verbose - language, but can scale your existing skills. + +Key Features are: + +* Extend sh scripts with variables +* Add error handling if single lines in sh scripts fail +* Overload variables and scripts in a environmant configuratiuon + +PSH is intended to be a **simple** and **easy** alternative other build script solutions. + +Installation +------------ + +Although you can use psh as a composer dependency, we recommend to use the *PHAR archive* instead. PSH only communicates through +the shell with your application and therefore does not need any influence on your other project dependencies. + +### Through composer ``` -./psh build #Create the release phar in build/psh.phar -./psh unit #Execute the unit and mutation suite +composer require shopware/psh --dev ``` -## Usage +### As a PHAR archive -### Configuration +Download `psh.phar` to your local environment. -Create a config file named `.psh.yaml` in your base directory an example file could look like this: +``` +wget shop.ware/psh.phar +chmod +x psh.phar +``` + +### PHAR creation ``` -header: | - SHOPWARE PHP-SH +./psh build +``` -paths: - - scripts/specific - - scripts/common - -templates: - - source: templates/consts.tpl - destination: app/consts.php +Psh is used to build itself. This will create a release phar in the `build/psh.phar` directory. Although the project itself requires PHP7 a + PHP 5.6 compatible version is created with it `build/psh56.phar`. This can be useful if your CI environment is not as recent as your development machines. -const: - env: prod - host: http://www.selfish.de +### Testing -dynamic: - id: id - lsahl: ll - -environments: - docker: - scripts - - - "dev-ops/scripts/docker" - dynamic: - id: "500:20" - const: - docker: "1" ``` - -This will: +./psh.phar unit +``` -* Output `Shopware PHP-SH` as the header of each command -* load *.sh and *.psh files from scripts/specific, scripts/common, dev-ops/scripts/docker -* Replace __ENV__ and __HOST__ in these files with the constant values -* Execute `id` and `ll` and replace __ID__ and __LSAHL__ with the output -* Load additional commands from the docker environment and prefix them with `docker:_NAME_` -* Create or overwrite the template destination files from the source template and replace variables according to the current environment. +Execute the Unit-Test suite and mutation testing through `humbug`. -### Writing SH-Scripts +Usage +------------ -Of course you can just reuse your existing sh scripts and they should work just fine. If not, please open an issue in the issue tracker. +## Writing SH-Scripts Keep in mind: **Commands will be validated for successful execution -> All failures will fail the script!** -#### Specials +### Including other scripts -There are some *special syntax* changes here: +Prefixing a line with `INCLUDE: ` will treat the rest of the line as a path to another script to be included and executed here. -* Prefixing a line with `I: ` will trigger it to ignore the errors. -* Prefixing a line with `INCLUDE: ` will treat the rest of the line as a path assignment to another script to be included here. -* Prefixing a line with `TTY: ` will enable the TTY mode for the following command, this enables you to add ssh statements. -* Prefixing a line with three spaces will append the line to the previous statement allowing for easy multi line statements. +``` +INCLUDE: my/sub/script.sh +``` -#### Downsides +If the path is relative. PSH will atempt to load the script relative to the location of the current script or relative to the configuration file. + +### Open a ssh connection to another machine -* Variables and exports do not work +Many dev-ops script open a SSH channel to a locally running virtual machine / container or a remote staging / test system. If you do this +through psh you have to prefix the line with `TTY:` -#### Variables +``` +TTY: vagrant ssh +``` -All Variables must start with `__`, end with `__` and contain upper case letters and `_` only. Even if configured as lower case they will be converted to upper case before the replacement takes place. - - -#### Example Script +### Ignoring if a statement errored + +Contrary to your usual shell scripts, to psh it matters if a sh statement fails or not. If you need it to ignore errors, you have to prefix the line with `I:` ``` -#!/usr/bin/env bash +I: rm -R sometimes/there +``` +## Breaking statements into multiple lines -ls -al -I: chmod +x /dir -INCLUDE: simple.sh +If a single shell statement is to long for a single line, you can break it in psh and intend it with three spaces in the next line. +PSH will then concatenate it prior to execution and execute it all in one. +``` bin/phpunit --debug --verbose ``` + +#### Downsides + +* `export` statements and internal variables do not work, since the statements do no longer share a single environment. +* Statements that change the flow of a script do not work out of the box. + +## Configuration + +Create a config file named `.psh.yaml` in your base directory. The minimum required file looks like this: + +``` +paths: + - my/sh/scripts + +const: [] + +dynamic: [] +``` + +* `paths` - The locations of your `*.sh` scripts +* `const` - The constant environment values you want psh to replace in your scripts +* `dynamic` - The dynamic values you want psh to replace in your scripts + +This just lists all `*.sh` scripts in `my/sh/scripts` and allows you to call them by filename. + +#### Placeholders + +Placeholders in your scripts looks like this: + +``` +ln -s __PATH__ +``` + +The placeholder `__PATH__` now needs to be part of your configuration file as either a constant or a variable. + +> Notice: All placeholders must be written in uppercase. Even if defined otherwise in configuration, replacement only works uppercase. + +#### Constants + +Constants are the basic solution to placeholder replacement. You define placeholders in your config like this: + +``` +const: + PATH: /var/www +``` + +This will then execute + +``` +ln -s /var/www +``` + +#### Variables + +With variables you can use the output of one line shell statements in your scripts. + +``` +dynamic: + PATH: echo $HOME +``` + +This is equivalent to: + +``` +ln -s `echo $HOME` +``` + +### Templates + +If your application depends on files that are not part of your repository because they differ for different systems (Typically `*.dist` files), +you can use templates to achieve automatic deployment of these files. + +``` +templates: + - source: templates/consts.tpl + destination: app/consts.php +``` + +This reads the contents of `templates/consts.tpl`, replaces placeholders with constants or variables from your configuration and writes the result to `app/consts.php`. + +#### Environments + +Environments are used to extend or overwrite your base configuration. You can add more scripts, redefine or add constants or variables. +A environemnt called `foo` may look like this: + +``` +environments: + foo: + paths: + - foo/sh/scripts + const: + TEST: 1 + dynamic: + ID: id +``` + +This environment loads all scripts from `foo/sh/scripts`, adds a constant `TEST` and a variable `ID`. +If you want to call a script in this environment you have to prefix the call with `foo:`. + + +### Headers + +Optionally - and just for fun - you can output a ASCII header in front of every PSH execution. + +``` +header: | + _ + ___| |__ ___ _ ____ ____ _ _ __ ___ + / __| '_ \ / _ \| '_ \ \ /\ / / _` | '__/ _ \ + \__ \ | | | (_) | |_) \ V V / (_| | | | __/ + |___/_| |_|\___/| .__/ \_/\_/ \__,_|_| \___| + |_| +``` + diff --git a/tests/Acceptance/ApplicationTest.php b/tests/Acceptance/ApplicationTest.php index 08a0cde..e76459d 100644 --- a/tests/Acceptance/ApplicationTest.php +++ b/tests/Acceptance/ApplicationTest.php @@ -1,9 +1,8 @@ cliMate->output->add('out', new MockWriter()); - $application->cliMate->output->add('error', new MockWriter()); - $application->cliMate->output->add('buffer', new MockWriter()); - $application->cliMate->output->defaultTo('out'); + MockWriter::addToApplication($application); $application->run([]); @@ -33,12 +28,8 @@ public function test_application_listing() public function test_application_execution() { - MockWriter::$content = ''; $application = new Application(__DIR__ . '/_app'); - $application->cliMate->output->add('out', new MockWriter()); - $application->cliMate->output->add('error', new MockWriter()); - $application->cliMate->output->add('buffer', new MockWriter()); - $application->cliMate->output->defaultTo('out'); + MockWriter::addToApplication($application); $application->run(['', 'simple']); @@ -53,12 +44,9 @@ public function test_application_execution() public function test_environment_application_execution() { - MockWriter::$content = ''; $application = new Application(__DIR__ . '/_app'); - $application->cliMate->output->add('out', new MockWriter()); - $application->cliMate->output->add('error', new MockWriter()); - $application->cliMate->output->add('buffer', new MockWriter()); - $application->cliMate->output->defaultTo('out'); + MockWriter::addToApplication($application); + $application->run(['', 'test:env']); @@ -71,18 +59,3 @@ public function test_environment_application_execution() self::assertStringEqualsFile(__DIR__ . '/_app/result.txt', 'test'); } } - -class MockWriter implements WriterInterface -{ - public static $content = ''; - - /** - * @param string $content - * - * @return void - */ - public function write($content) - { - self::$content .= $content; - } -} diff --git a/tests/Acceptance/MinApplicationTest.php b/tests/Acceptance/MinApplicationTest.php new file mode 100644 index 0000000..bf9dc69 --- /dev/null +++ b/tests/Acceptance/MinApplicationTest.php @@ -0,0 +1,20 @@ +run([]); + + $this->assertNotFalse(strpos(MockWriter::$content, '1 script(s) available')); + } +} \ No newline at end of file diff --git a/tests/Acceptance/MockWriter.php b/tests/Acceptance/MockWriter.php new file mode 100644 index 0000000..6c9c8d9 --- /dev/null +++ b/tests/Acceptance/MockWriter.php @@ -0,0 +1,32 @@ +cliMate->output->add('out', new self()); + $application->cliMate->output->add('error', new self()); + $application->cliMate->output->add('buffer', new self()); + $application->cliMate->output->defaultTo('out'); + } +} \ No newline at end of file diff --git a/tests/Acceptance/_minApp/.psh.yml b/tests/Acceptance/_minApp/.psh.yml new file mode 100644 index 0000000..a502b5d --- /dev/null +++ b/tests/Acceptance/_minApp/.psh.yml @@ -0,0 +1,6 @@ +paths: + - my/sh/scripts + +const: [] + +dynamic: [] \ No newline at end of file diff --git a/tests/Acceptance/_minApp/my/sh/scripts/test.sh b/tests/Acceptance/_minApp/my/sh/scripts/test.sh new file mode 100644 index 0000000..afbc6bc --- /dev/null +++ b/tests/Acceptance/_minApp/my/sh/scripts/test.sh @@ -0,0 +1,3 @@ +#!/usr/bin/env bash + +ln -s From 5d68849c8d333b1459736eb479e76f3c9f783859 Mon Sep 17 00:00:00 2001 From: Jan Pietrzyk Date: Tue, 30 Aug 2016 14:31:08 +0200 Subject: [PATCH 4/9] add travis config --- .travis.yml | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 .travis.yml diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..3c9c2ec --- /dev/null +++ b/.travis.yml @@ -0,0 +1,17 @@ +language: php + +php: + - 7.0 + +sudo: false + +cache: + directories: + - $HOME/.composer/cache + +before_script: + - composer self-update + - composer install + +script: + - ./psh unit From 1e12b73d970777e7bbdb546f421e94189d66db76 Mon Sep 17 00:00:00 2001 From: Jan Pietrzyk Date: Wed, 31 Aug 2016 09:44:46 +0200 Subject: [PATCH 5/9] fix code style --- src/Application/Application.php | 2 +- src/Application/ApplicationFactory.php | 2 +- src/Application/ClimateLogger.php | 2 +- src/Config/Config.php | 2 +- src/Config/ConfigBuilder.php | 2 +- src/Config/ConfigEnvironment.php | 2 +- src/Config/ConfigFileFinder.php | 2 +- src/Config/ConfigLoader.php | 2 +- src/Config/YamlConfigFileLoader.php | 2 +- src/Listing/Script.php | 2 +- src/Listing/ScriptFinder.php | 2 +- src/Listing/ScriptNotFoundException.php | 2 +- src/ScriptRuntime/Command.php | 2 +- src/ScriptRuntime/CommandBuilder.php | 2 +- src/ScriptRuntime/ExecutionErrorException.php | 2 +- src/ScriptRuntime/Logger.php | 2 +- src/ScriptRuntime/ProcessEnvironment.php | 2 +- src/ScriptRuntime/ProcessExecutor.php | 2 +- src/ScriptRuntime/ProcessValueProvider.php | 2 +- src/ScriptRuntime/ScriptLoader.php | 2 +- src/ScriptRuntime/SimpleValueProvider.php | 2 +- src/ScriptRuntime/Template.php | 2 +- src/ScriptRuntime/TemplateEngine.php | 2 +- src/ScriptRuntime/ValueProvider.php | 2 +- tests/Acceptance/ApplicationTest.php | 2 +- tests/Acceptance/MinApplicationTest.php | 5 ++--- tests/Acceptance/MockWriter.php | 5 ++--- tests/BlackholeLogger.php | 2 +- tests/Integration/Config/ConfigFileFinderTest.php | 2 +- tests/Integration/Listing/ScriptFinderTest.php | 2 +- tests/Integration/ScriptRuntime/ProcessExecutorTest.php | 2 +- tests/Integration/ScriptRuntime/TemplateTest.php | 2 +- tests/Integration/ScriptRuntime/_test_write.tpl | 0 tests/Unit/Config/ConfigFileFinderTest.php | 2 +- tests/Unit/Config/YamlConfigFileLoaderTest.php | 3 +-- tests/Unit/Listing/ScriptFinderTest.php | 2 +- tests/Unit/ScriptRuntime/ProcessEnvironmentTest.php | 2 +- tests/Unit/ScriptRuntime/ScriptLoaderTest.php | 2 +- tests/Unit/ScriptRuntime/TemplateEngineTest.php | 2 +- tests/bootstrap.php | 2 +- 40 files changed, 41 insertions(+), 44 deletions(-) delete mode 100644 tests/Integration/ScriptRuntime/_test_write.tpl diff --git a/src/Application/Application.php b/src/Application/Application.php index cea563d..30492f1 100644 --- a/src/Application/Application.php +++ b/src/Application/Application.php @@ -1,4 +1,4 @@ -assertNotFalse(strpos(MockWriter::$content, '1 script(s) available')); } -} \ No newline at end of file +} diff --git a/tests/Acceptance/MockWriter.php b/tests/Acceptance/MockWriter.php index 6c9c8d9..0814f71 100644 --- a/tests/Acceptance/MockWriter.php +++ b/tests/Acceptance/MockWriter.php @@ -1,8 +1,7 @@ -cliMate->output->add('buffer', new self()); $application->cliMate->output->defaultTo('out'); } -} \ No newline at end of file +} diff --git a/tests/BlackholeLogger.php b/tests/BlackholeLogger.php index 746de7c..c02efd2 100644 --- a/tests/BlackholeLogger.php +++ b/tests/BlackholeLogger.php @@ -1,4 +1,4 @@ - Date: Wed, 31 Aug 2016 10:00:37 +0200 Subject: [PATCH 6/9] add travis build and phar deployment --- .travis.yaml | 0 .travis.yml | 6 ++++++ deploy.sh | 34 ++++++++++++++++++++++++++++++++++ 3 files changed, 40 insertions(+) delete mode 100644 .travis.yaml create mode 100755 deploy.sh diff --git a/.travis.yaml b/.travis.yaml deleted file mode 100644 index e69de29..0000000 diff --git a/.travis.yml b/.travis.yml index 3c9c2ec..c6fc6c2 100644 --- a/.travis.yml +++ b/.travis.yml @@ -10,8 +10,14 @@ cache: - $HOME/.composer/cache before_script: + - openssl aes-256-cbc -K $encrypted_d4931f6d241c_key -iv $encrypted_d4931f6d241c_iv -in .travis/github_deploy_key.enc -out .travis/github_deploy_key -d - composer self-update - composer install script: - ./psh unit + +after_success: + - ./psh build + - chmod +x actions/deploy.sh + - ./deploy.sh diff --git a/deploy.sh b/deploy.sh new file mode 100755 index 0000000..7c4af01 --- /dev/null +++ b/deploy.sh @@ -0,0 +1,34 @@ +#!/bin/bash + +ls -ahl .travis/ + +# Setup SSH agent +chmod 600 .travis/github_deploy_key +eval "$(ssh-agent -s)" +ssh-add .travis/github_deploy_key + +# Setup git defaults +git config --global user.email "contact@shopware.com" +git config --global user.name "shopwareBot" + +# Add SSH-based remote +git remote add deploy git@github.com:shopwareLabs/psh.git +git fetch deploy + +## Checkout gh-pages and add PHAR file and version +git checkout -b gh-pages deploy/gh-pages +mv build/psh.phar psh.phar +sha1sum psh.phar > psh.phar.version + +mv build/psh56.phar psh56.phar +sha1sum psh56.phar > psh56.phar.version + +git add psh.phar psh.phar.version psh56.phar psh56.phar.version + +git status + + +# Commit and push +git commit -m 'Rebuilt phar' +git log +git push deploy gh-pages:gh-pages \ No newline at end of file From deacc9ec8bcf4c5078cf43903f4bed9bbe60ea08 Mon Sep 17 00:00:00 2001 From: Jan Philipp Pietrzyk Date: Wed, 31 Aug 2016 12:30:23 +0200 Subject: [PATCH 7/9] updated readme --- README.md | 152 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 80 insertions(+), 72 deletions(-) diff --git a/README.md b/README.md index 404bdee..3368fb3 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,24 @@ PSH - PHP shell helper ==================== +PSH is intended to be a **simple** and **easy** alternative other build script solutions. + Introduction ------------ -A Tool to execute shell scripts through php, including a small templating engine and environment settings. It can be used -as an easy way to create adaptable dev-ops scripts from existing or newly written shell scripts. You do not have to learn -a new - and in most cases much more verbose - language, but can scale your existing skills. +You do not have to learn a new - and in most cases much more verbose - language, but can scale your existing skills +on the command line Key Features are: -* Extend sh scripts with variables -* Add error handling if single lines in sh scripts fail -* Overload variables and scripts in a environmant configuratiuon +* Add error handling if single statement in the sh scripts fails +* Replace placeholders in sh scripts with variables +* Overload variables and scripts in a environment configuration -PSH is intended to be a **simple** and **easy** alternative other build script solutions. - Installation ------------ -Although you can use psh as a composer dependency, we recommend to use the *PHAR archive* instead. PSH only communicates through +Although you can use PSH as a composer dependency, we recommend to use the *PHAR archive* instead. PSH only communicates through the shell with your application and therefore does not need any influence on your other project dependencies. ### Through composer @@ -28,84 +27,42 @@ the shell with your application and therefore does not need any influence on you composer require shopware/psh --dev ``` -### As a PHAR archive +### As a PHAR archive (preferred) Download `psh.phar` to your local environment. ``` -wget shop.ware/psh.phar +wget https://shopwarelabs.github.io/psh/psh.phar # PHP7 Version +# OR wget https://shopwarelabs.github.io/psh/psh56.phar for the PHP5.6 Version chmod +x psh.phar ``` -### PHAR creation +### Build it yourself + +PSH is used to build itself. You need to clone the repository and install the composer dependencies by yourself first. ``` +git clone https://github.com/shopwareLabs/psh.git +cd psh +composer install # assuming you have composer installed globally + +./psh unit ./psh build ``` -Psh is used to build itself. This will create a release phar in the `build/psh.phar` directory. Although the project itself requires PHP7 a - PHP 5.6 compatible version is created with it `build/psh56.phar`. This can be useful if your CI environment is not as recent as your development machines. +After installing you should execute the test suite in order to verify your installation. -### Testing - -``` -./psh.phar unit -``` - -Execute the Unit-Test suite and mutation testing through `humbug`. +This will create a release phar in the `build/psh.phar` directory. Although the project itself requires PHP7 a PHP 5.6 +compatible version is currently created with it `build/psh56.phar`. Usage ------------ -## Writing SH-Scripts - -Keep in mind: **Commands will be validated for successful execution -> All failures will fail the script!** - -### Including other scripts - -Prefixing a line with `INCLUDE: ` will treat the rest of the line as a path to another script to be included and executed here. - -``` -INCLUDE: my/sub/script.sh -``` - -If the path is relative. PSH will atempt to load the script relative to the location of the current script or relative to the configuration file. - -### Open a ssh connection to another machine - -Many dev-ops script open a SSH channel to a locally running virtual machine / container or a remote staging / test system. If you do this -through psh you have to prefix the line with `TTY:` - -``` -TTY: vagrant ssh -``` - -### Ignoring if a statement errored - -Contrary to your usual shell scripts, to psh it matters if a sh statement fails or not. If you need it to ignore errors, you have to prefix the line with `I:` - -``` -I: rm -R sometimes/there -``` -## Breaking statements into multiple lines - -If a single shell statement is to long for a single line, you can break it in psh and intend it with three spaces in the next line. -PSH will then concatenate it prior to execution and execute it all in one. - -``` -bin/phpunit - --debug - --verbose -``` - -#### Downsides - -* `export` statements and internal variables do not work, since the statements do no longer share a single environment. -* Statements that change the flow of a script do not work out of the box. +PSH is a CLI application. Before you can use it you need to create configuration `.psh.yml`. ## Configuration -Create a config file named `.psh.yaml` in your base directory. The minimum required file looks like this: +Create a config file named `.psh.yml` in your base directory. The minimum required file looks like this: ``` paths: @@ -117,8 +74,8 @@ dynamic: [] ``` * `paths` - The locations of your `*.sh` scripts -* `const` - The constant environment values you want psh to replace in your scripts -* `dynamic` - The dynamic values you want psh to replace in your scripts +* `const` - The constant environment values you want PSH to replace in your scripts +* `dynamic` - The dynamic values you want PSH to replace in your scripts This just lists all `*.sh` scripts in `my/sh/scripts` and allows you to call them by filename. @@ -164,7 +121,7 @@ This is equivalent to: ln -s `echo $HOME` ``` -### Templates +#### Templates If your application depends on files that are not part of your repository because they differ for different systems (Typically `*.dist` files), you can use templates to achieve automatic deployment of these files. @@ -197,7 +154,7 @@ This environment loads all scripts from `foo/sh/scripts`, adds a constant `TEST` If you want to call a script in this environment you have to prefix the call with `foo:`. -### Headers +#### Headers Optionally - and just for fun - you can output a ASCII header in front of every PSH execution. @@ -211,8 +168,59 @@ header: | |_| ``` +## SH-Scripts + +Although most of your existing sh scripts should work just fine, you may find some of the following additions useful or necessary. + +Keep in mind: **Commands will be validated for successful execution -> All failures will fail the script!** + +#### Defining placeholders + +In order to ensure that your scripts are reusable you can add placeholders that PSH will replace with configured values. All placeholders +start and end with `__`, and contain only upper case letters, numbers, and single `_` characters. + +``` +__TEST_IT__ +``` + +#### Including other scripts + +Prefixing a line with `INCLUDE: ` will treat the rest of the line as a path to another script to be included and executed here. + +``` +INCLUDE: my/sub/script.sh +``` + +If the path is relative. PSH will attempt to load the script relative to the location of the current script or relative to the configuration file. - +#### Open a ssh connection to another machine +Many dev-ops script open a SSH channel to a locally running virtual machine / container or a remote staging / test system. If you do this +through PSH you have to prefix the line with `TTY:` +``` +TTY: vagrant ssh +``` + +#### Ignoring if a statement errored + +Contrary to your usual shell scripts, to PSH it matters if a sh statement fails or not. If you need it to ignore errors, you have to prefix the line with `I:` + +``` +I: rm -R sometimes/there +``` +#### Breaking statements into multiple lines + +If a single shell statement is to long for a single line, you can break it in PSH and intend it with three spaces in the next line. +PSH will then concatenate it prior to execution and execute it all in one. + +``` +bin/phpunit + --debug + --verbose +``` +#### Downsides + +* `export` statements and internal variables do not work, since the statements do **no longer share a single environment**. +* Statements that change the flow of a script do not work out of the box. From 3ba7ca51f95ac3d9759a06e4e068fd8442e7e270 Mon Sep 17 00:00:00 2001 From: Jan Philipp Pietrzyk Date: Wed, 31 Aug 2016 12:51:22 +0200 Subject: [PATCH 8/9] update readme --- README.md | 57 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 29 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 3368fb3..0dc1d23 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,19 @@ PSH - PHP shell helper ==================== +**Keep using your standard shell scripts** + PSH is intended to be a **simple** and **easy** alternative other build script solutions. Introduction ------------ You do not have to learn a new - and in most cases much more verbose - language, but can scale your existing skills -on the command line +on the command line. -Key Features are: +Key benefits are: +* Share your existing shell scripts with the rest of your team * Add error handling if single statement in the sh scripts fails * Replace placeholders in sh scripts with variables * Overload variables and scripts in a environment configuration @@ -18,12 +21,12 @@ Key Features are: Installation ------------ -Although you can use PSH as a composer dependency, we recommend to use the *PHAR archive* instead. PSH only communicates through +Although you can use PSH as a composer dependency, we recommend to use the **PHAR archive** instead. PSH only communicates through the shell with your application and therefore does not need any influence on your other project dependencies. ### Through composer -``` +```sh composer require shopware/psh --dev ``` @@ -31,7 +34,7 @@ composer require shopware/psh --dev Download `psh.phar` to your local environment. -``` +```sh wget https://shopwarelabs.github.io/psh/psh.phar # PHP7 Version # OR wget https://shopwarelabs.github.io/psh/psh56.phar for the PHP5.6 Version chmod +x psh.phar @@ -41,30 +44,28 @@ chmod +x psh.phar PSH is used to build itself. You need to clone the repository and install the composer dependencies by yourself first. -``` +```sh git clone https://github.com/shopwareLabs/psh.git cd psh composer install # assuming you have composer installed globally -./psh unit +./psh unit # verify your installation by executing the test suite. ./psh build ``` -After installing you should execute the test suite in order to verify your installation. - This will create a release phar in the `build/psh.phar` directory. Although the project itself requires PHP7 a PHP 5.6 compatible version is currently created with it `build/psh56.phar`. Usage ------------ -PSH is a CLI application. Before you can use it you need to create configuration `.psh.yml`. +PSH is a CLI application. Before you can use it you need to create a configuration file in your project root named `.psh.yml`. ## Configuration -Create a config file named `.psh.yml` in your base directory. The minimum required file looks like this: +The minimum required file looks like this: -``` +```yaml paths: - my/sh/scripts @@ -83,26 +84,26 @@ This just lists all `*.sh` scripts in `my/sh/scripts` and allows you to call the Placeholders in your scripts looks like this: -``` +```sh ln -s __PATH__ ``` The placeholder `__PATH__` now needs to be part of your configuration file as either a constant or a variable. -> Notice: All placeholders must be written in uppercase. Even if defined otherwise in configuration, replacement only works uppercase. +> Notice: All placeholders must be written in uppercase in scripts. Even if defined otherwise in configuration, replacement only works uppercase. #### Constants Constants are the basic solution to placeholder replacement. You define placeholders in your config like this: -``` +```yaml const: PATH: /var/www ``` This will then execute -``` +```sh ln -s /var/www ``` @@ -110,14 +111,14 @@ ln -s /var/www With variables you can use the output of one line shell statements in your scripts. -``` +```yaml dynamic: PATH: echo $HOME ``` -This is equivalent to: +The Variables get executed before the actual statement is executed, but you can imgine the outcome to be equivalent to: -``` +```yaml ln -s `echo $HOME` ``` @@ -126,7 +127,7 @@ ln -s `echo $HOME` If your application depends on files that are not part of your repository because they differ for different systems (Typically `*.dist` files), you can use templates to achieve automatic deployment of these files. -``` +```yaml templates: - source: templates/consts.tpl destination: app/consts.php @@ -139,7 +140,7 @@ This reads the contents of `templates/consts.tpl`, replaces placeholders with co Environments are used to extend or overwrite your base configuration. You can add more scripts, redefine or add constants or variables. A environemnt called `foo` may look like this: -``` +```yaml environments: foo: paths: @@ -158,7 +159,7 @@ If you want to call a script in this environment you have to prefix the call wit Optionally - and just for fun - you can output a ASCII header in front of every PSH execution. -``` +```yaml header: | _ ___| |__ ___ _ ____ ____ _ _ __ ___ @@ -179,15 +180,15 @@ Keep in mind: **Commands will be validated for successful execution -> All failu In order to ensure that your scripts are reusable you can add placeholders that PSH will replace with configured values. All placeholders start and end with `__`, and contain only upper case letters, numbers, and single `_` characters. -``` +```sh __TEST_IT__ ``` #### Including other scripts -Prefixing a line with `INCLUDE: ` will treat the rest of the line as a path to another script to be included and executed here. +Prefixing a line with `INCLUDE: ` will treat the rest of the line as the path to another script to be included and executed here. -``` +```sh INCLUDE: my/sub/script.sh ``` @@ -198,7 +199,7 @@ If the path is relative. PSH will attempt to load the script relative to the loc Many dev-ops script open a SSH channel to a locally running virtual machine / container or a remote staging / test system. If you do this through PSH you have to prefix the line with `TTY:` -``` +```sh TTY: vagrant ssh ``` @@ -206,7 +207,7 @@ TTY: vagrant ssh Contrary to your usual shell scripts, to PSH it matters if a sh statement fails or not. If you need it to ignore errors, you have to prefix the line with `I:` -``` +```sh I: rm -R sometimes/there ``` #### Breaking statements into multiple lines @@ -214,7 +215,7 @@ I: rm -R sometimes/there If a single shell statement is to long for a single line, you can break it in PSH and intend it with three spaces in the next line. PSH will then concatenate it prior to execution and execute it all in one. -``` +```sh bin/phpunit --debug --verbose From 79756fa1d076b2e936ae8f5cac15b653077589c6 Mon Sep 17 00:00:00 2001 From: Jan Philipp Pietrzyk Date: Wed, 31 Aug 2016 12:53:45 +0200 Subject: [PATCH 9/9] restrict phar builds to master --- .travis.yml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/.travis.yml b/.travis.yml index c6fc6c2..e18aa1c 100644 --- a/.travis.yml +++ b/.travis.yml @@ -18,6 +18,5 @@ script: - ./psh unit after_success: - - ./psh build - - chmod +x actions/deploy.sh - - ./deploy.sh + - if [[ $TRAVIS_BRANCH == 'master' && $TRAVIS_PULL_REQUEST == 'false' ]]; then ./psh build; fi + - if [[ $TRAVIS_BRANCH == 'master' && $TRAVIS_PULL_REQUEST == 'false' ]]; then ./deploy.sh; fi