From ba59f99026ce412b52ba18c83675710a50a7fd5b Mon Sep 17 00:00:00 2001 From: Tim Smith Date: Wed, 17 Feb 2016 12:17:06 -0800 Subject: Document more advanced usage Fix badge and some formatting as well --- README.md | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 7f463e0..4a9bf34 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,12 @@ # Mixlib::ShellOut -[![Build Status Master](https://travis-ci.org/chef/mixlib-shellout.svg?branch=master)](https://travis-ci.org/chef/mixlib-shellout) -[![Build Status Master](https://ci.appveyor.com/api/projects/status/github/chef/mixlib-shellout?branch=master&svg=true&passingText=master%20-%20Ok&pendingText=master%20-%20Pending&failingText=master%20-%20Failing)](https://ci.appveyor.com/project/Chef/mixlib-shellout/branch/master) -[![Gem Version](https://badge.fury.io/rb/mixlib-shellout.svg)](https://badge.fury.io/rb/mixlib-shellout) +[![Build Status Master](https://travis-ci.org/chef/mixlib-shellout.svg?branch=master)](https://travis-ci.org/chef/mixlib-shellout) [![Build Status Master](https://ci.appveyor.com/api/projects/status/github/chef/mixlib-shellout?branch=master&svg=true&passingText=master%20-%20Ok&pendingText=master%20-%20Pending&failingText=master%20-%20Failing)](https://ci.appveyor.com/project/Chef/mixlib-shellout/branch/master) [![Gem Version](https://badge.fury.io/rb/mixlib-shellout.svg)](https://badge.fury.io/rb/mixlib-shellout) Provides a simplified interface to shelling out while still collecting both standard out and standard error and providing full control over environment, working directory, uid, gid, etc. No means for passing input to the subprocess is provided. ## Example +### Simple Shellout Invoke find(1) to search for .rb files: ```ruby @@ -34,14 +33,21 @@ Raise an exception if it didn't exit with 0 find.error! ``` -Run a command as the `www` user with no extra ENV settings from `/tmp` +### Advanced Shellout +In addition to the command to run there are other attributes that can be set to change the shellout behavior: +- `env`: set environmental variables before shelling out +- `user`: execute the shellout as this user +- `cwd`: execute the shellout from this directory +- `timeout`: set a command timeout (defaul 600s) + +Run a command as the `www` user with no extra ENV settings from `/tmp` with a 1s timeout ```ruby - cmd = Mixlib::ShellOut.new("apachectl", "start", :user => 'www', :env => nil, :cwd => '/tmp') + cmd = Mixlib::ShellOut.new("apachectl", "start", :user => 'www', :env => nil, :cwd => '/tmp', :timeout => 1) cmd.run_command # etc. ``` -## STDIN Example +### STDIN Example Invoke crontab to edit user cron: ```ruby @@ -51,7 +57,7 @@ Invoke crontab to edit user cron: crontab.run_command ``` -## Windows Impersonation Example +### Windows Impersonation Example Invoke "whoami.exe" to demonstrate running a command as another user: ```ruby @@ -67,9 +73,8 @@ Mixlib::ShellOut does a standard fork/exec on Unix, and uses the Win32 API on Wi - [https://github.com/rtomayko/posix-spawn](https://github.com/rtomayko/posix-spawn) ## License - -* Copyright:: Copyright (c) 2011-2016 Chef Software, Inc. -* License:: Apache License, Version 2.0 +- Copyright:: Copyright (c) 2011-2016 Chef Software, Inc. +- License:: Apache License, Version 2.0 ```text Licensed under the Apache License, Version 2.0 (the "License"); -- cgit v1.2.1