benry-unixcmd 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 73411bbc7b8bd31e455acdc67c7ef3d12df08ec3aa0bab56d631fcf12395b34b
+  data.tar.gz: 9fadc9355cf0006c83f48835c55197a4a9498a49b7e03f752af86eb951f03691
+SHA512:
+  metadata.gz: 14462cad893ee39cc9e9ae27977b0a71c76fd2b142c2878c14f52f93f9471186a66d2ed895d8e62b53ea3565b5312cd49782d4b1e9c3a8fc0eafcc38c6c53197
+  data.tar.gz: 309f3813307636ff6adbe9b72f39fd01a4edf1bcf304b97ead6abd74787742795d7686fc40ededd3b97aa60816bea05dca3670a7e80a9999f6ae92b6acf126bb

data/CHANGES.md

@@ -0,0 +1,10 @@
+=======
+CHANGES
+=======
+
+
+
+Release X.X.X
+-------------
+
+* First public release

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 kuwata-lab.com
+
+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.

data/README.md

@@ -0,0 +1,936 @@
+benry-unixcmd Gem README
+========================
+
+($Release: 0.9.0 $)
+
+benry-unixcmd gem implements popular UNIX commands, like FileUtils.
+
+Features compared to FileUtils:
+
+* supports file patterns (`*`, `.`, `{}`) directly.
+* provides `cp :r`, `mv :p`, `rm :rf`, ... instead of `cp_r`, `mv_p`, `rm_rf`, ...
+* prints command prompt `$ ` before command echoback.
+* provides `pushd` which is similar to `cd` but supports nested calls naturally.
+* implements `capture2`, `capture2e`, and `capture3` which calls
+  `Popen3.capture2`, `Popen3.capture2`, and `Popen3.capture3` respectively.
+* supports `touch -r reffile`.
+* provides `sys` command which is similar to `sh` in Rake but different in details.
+* provides `zip` and `unzip` commands (requires `rubyzip` gem).
+* provides `store` command which copies files recursively into target directory, keeping file path.
+* provides `atomic_symlink!` command which switches symlink atomically.
+
+(benry-unixcmd gem requires Ruby >= 2.3)
+
+
+
+Table of Contents
+=================
+
+<!-- TOC -->
+
+* <a href="#install">Install</a>
+* <a href="#command-reference">Command Reference</a>
+  * <a href="#echo"><code>echo</code></a>
+  * <a href="#echoback"><code>echoback</code></a>
+  * <a href="#cp"><code>cp</code></a>
+  * <a href="#mv"><code>mv</code></a>
+  * <a href="#rm"><code>rm</code></a>
+  * <a href="#mkdir"><code>mkdir</code></a>
+  * <a href="#rmdir"><code>rmdir</code></a>
+  * <a href="#ln"><code>ln</code></a>
+  * <a href="#atomic_symlink"><code>atomic_symlink!</code></a>
+  * <a href="#touch"><code>touch</code></a>
+  * <a href="#chmod"><code>chmod</code></a>
+  * <a href="#chown"><code>chown</code></a>
+  * <a href="#pwd"><code>pwd</code></a>
+  * <a href="#store"><code>store</code></a>
+  * <a href="#sys"><code>sys</code></a>
+  * <a href="#ruby"><code>ruby</code></a>
+  * <a href="#capture2"><code>capture2</code></a>
+  * <a href="#capture2e"><code>capture2e</code></a>
+  * <a href="#capture3"><code>capture3</code></a>
+  * <a href="#zip"><code>zip</code></a>
+  * <a href="#unzip"><code>unzip</code></a>
+  * <a href="#time"><code>time</code></a>
+* <a href="#faq">FAQ</a>
+  * <a href="#why-mv-or-cp-requires-to-option">Why <code>mv</code> or <code>cp</code> requires <code>to:</code> option?</a>
+  * <a href="#how-to-use-in-rakefile">How to use in Rakefile?</a>
+  * <a href="#how-to-change-prompt-string">How to change prompt string?</a>
+  * <a href="#how-to-make-prompt-colored">How to make prompt colored?</a>
+  * <a href="#how-to-disable-command-echoback">How to disable command echoback?</a>
+* <a href="#license-and-copyright">License and Copyright</a>
+
+<!-- /TOC -->
+
+
+
+Install
+=======
+
+```
+$ gem install benry-unixcmd
+```
+
+File: ex1.rb
+
+```ruby
+require 'benry/unixcmd'      # !!!!!
+include Benry::UnixCommand   # !!!!!
+
+output = capture2 "ls -al"   # run command and return output
+#print output
+```
+
+Result:
+
+```terminal
+[localhost] ruby ex1.rb
+$ ls -al
+```
+
+
+
+Command Reference
+=================
+
+
+
+`echo`
+------
+
+File: ex-echo1.rb
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+echo "aa", "bb", "cc"
+
+echo :n, "aa"        # not print "\n"
+echo "bb"
+```
+
+Result:
+
+```terminal
+[localhost]$ ruby ex_echo1.rb
+$ echo aa bb cc
+aa bb cc
+$ echo -n aa
+aa$ echo bb
+bb
+```
+
+Options:
+
+* `echo :n` -- don't print "\n".
+
+
+
+`echoback`
+----------
+
+* `echoback "command"` prints `$ command` string into stdout.
+* `echoback "command"` indents command if in block of `cd` or `pushd`.
+
+File: ex-echoback1.rb
+
+```
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+echoback "command 123"
+cd "dir1" do
+  echoback "command 456"
+  cd "dir2" do
+    echoback "command 789"
+  end
+end
+```
+
+Result:
+
+```terminal
+[localhost]$ ruby ex_echoback1.rb
+$ command 123
+$ cd dir1
+$  command 456
+$  cd dir2
+$   command 789
+$  cd -
+$ cd -
+```
+
+
+
+`cp`
+----
+
+* `cp "x", "y"` copies `x` to new file `y'. Fails when `y` already exists.
+* `cp! "x", "y"` is similar to above, but overwrites `y` even if it exists.
+* `cp "x", "y", to: "dir"` copies `x` and `y` into `dir`.
+* `cp "x", "y", "dir"` will be error! (use `to: "dir"` instead.)
+* Glob pattern such as `*`, `**`, `?`, and `{}` are available.
+* (See [FAQ](#faq) about `to:` keyword option.)
+
+<!--
+File: ex-cp1.rb
+-->
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+## copy file to newfile
+cp  "file1.txt", "newfile.txt"      # error if newfile.txt already exists.
+cp! "file1.txt", "newfile.txt"      # overrides newfile.txt if exists.
+
+## copy dir to newdir recursively
+cp :r, "dir1", "newdir"             # error if newdir already exists.
+
+## copy files to existing directory
+cp :pr, "file*.txt", "lib/**/*.rb", to: "dir1"   # error if dir1 not exist.
+```
+
+Options:
+
+* `cp :p` -- preserves timestamps and permission.
+* `cp :r` -- copies files and directories recursively.
+* `cp :l` -- creates hard links instead of copying files.
+* `cp :f` -- ignores non-existing source files.
+             Notice that this is different from `cp -f` of unix command.
+
+
+
+`mv`
+----
+
+* `mv "x", "y"` renames `x` to `y`. Fails when `y` already exists.
+* `mv! "x", "y"` is similar to above, but overwrites `y` even if it exists.
+* `mv "x", "y", to: "dir"` moves `x` and `y` into `dir`.
+* `mv "x", "y", "dir"` will be error! (use `to: "dir"` instead.)
+* Glob patten such as `*`, `**`, `?`, and `{}` are available.
+* (See [FAQ](#faq) about `to:` keyword option.)
+
+<!--
+File: ex-mv1.rb
+-->
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+## rename file
+mv  "file1.txt", "newfile.txt"      # error if newfile.txt already exists.
+mv! "file1.txt", "newfile.txt"      # overrides newfile.txt if exists.
+
+## rename directory
+mv "dir1", "newdir"                 # error if newdir already exists.
+
+## move files and directories to existing directory
+mv "file*.txt", "lib", to: "dir1"   # error if dir1 not exist.
+
+## ignore non-existing files.
+mv     "foo*.txt", to: "dir1"       # error if foo*.txt not exist.
+mv :f, "foo*.txt", to: "dir1"       # not error even if foo*.txt not exist.
+```
+
+Options:
+
+* `mv :f` -- ignores non-existing source files.
+
+
+
+`rm`
+----
+
+* `rm "x", "y"` removes file `x` and `y`.
+* `rm :r, "dir1"` removes directory recursively.
+* `rm "dir1"` will raise error because `:r` option not specified.
+* `rm "foo*.txt"` will raise error if `foo*.txt` not exists.
+* `rm :f, "foo*.txt"` will not raise error even if `foo*.txt` not exists.
+* Glob patten such as `*`, `**`, `?`, and `{}` are available.
+
+<!--
+File: ex-rm1.rb
+-->
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+## remove files
+rm  "foo*.txt", "bar*.txt"          # error if files not exist.
+rm :f, "foo*.txt", "bar*.txt"       # not error even if files not exist.
+
+## remove directory
+rm :r,  "dir1"                      # error if dir1 not exist.
+rm :rf, "dir1"                      # not error even if dir1 not exist.
+```
+
+Options:
+
+* `rm :r` -- remove files and directories recursively.
+* `rm :f` -- ignores non-existing files and directories.
+
+
+
+`mkdir`
+-------
+
+* `mkdir "x", "y"` creates `x` and `y` directories.
+* `mkdir :p, "x/y/z"` creates `x/y/z` directory.
+* `mkdir "x"` will be error if `x` already exists.
+* `mkdir :p, "x"` will not be error even if `x` already exists.
+* `mkdir :m, 0775, "x"` creates new directory with permission 0775.
+
+<!--
+File: ex-mkdir1.rb
+-->
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+## creates new directory
+mkdir "newdir"
+
+## creates new directory with path
+mkdir :p, "dir/x/y/z"
+
+## creats new directory with specific permission
+mkdir :m, 0755, "newdir"
+```
+
+Options:
+
+* `mkdir :p` -- creates intermediate path.
+* `mkdir :m, 0XXX` -- specifies directory permission.
+
+
+
+`rmdir`
+-------
+
+* `rmdir "x", "y"` removed empty directores.
+* Raises error when directory not empty.
+
+<!--
+File: ex-rmdir1.rb
+-->
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+## remove empty directory
+rmdir "dir"     # error if directory not empty.
+```
+
+Options:
+
+* (no options)
+
+
+
+`ln`
+----
+
+* `ln "x", "y"` creates hard link.
+* `ln :s, "x", "y"` creates symbolic link. Error if `y` already exists.
+* `ln! :s, "x", "y"` overwrites existing symbolic link `y`.
+* `ln "files*.txt', to: "dir"` creates hard links into `dir`.
+* `ln "files*.txt', "dir"` will be error! (use `to: "dir"` instead.)
+* (See [FAQ](#faq) about `to:` keyword option.)
+
+<!--
+File: ex-ln1.rb
+-->
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+## create hard link
+ln "foo1.txt", "dir/foo1.txt"
+
+## create symbolic link
+ln :s, "foo1.txt", "dir/foo1.txt"     # error if dir/foo1.txt alreay exists.
+ln! :s, "foo1.txt", "dir/foo1.txt"    # overwrites dir/foo1.txt if exists.
+
+## create symbolic link into directory.
+ln :s, "foo1.txt", to: "dir"
+
+## error! use `to: "dir"` instead.
+ln :s, "foo1.txt", "dir"
+```
+
+
+
+`atomic_symlink!`
+-----------------
+
+* `atomic_symlink! "x", "y"` creates symbolic link atomically.
+
+<!--
+File: ex-atomic_symlink1.rb
+-->
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+## create symbolic link atomically
+atomic_symlink! "src-20200101", "src"
+
+## the above is same as the following
+tmplink = "src.#{rand().to_s[2..6]}"      # random name
+File.symlink("src-20200101", tmplink)     # create symblink with random name
+File.rename(tmplink, "src")               # rename symlink atomically
+```
+
+Options:
+
+* (no options)
+
+
+
+`touch`
+-------
+
+* `touch "x"` updates timestamp of file.
+* `touch :r, "reffile", "x"` uses timestamp of `reffile` instead current timestamp.
+
+<!--
+File: ex-touch1.rb
+-->
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+## updates timestamp of files to current timestamp.
+touch "files*.txt"
+
+## copy timestamp from reffile to other files.
+touch :r, "reffile", "files*.txt"
+```
+
+Options:
+
+* `touch :a` -- updates only access time.
+* `touch :m` -- updates only modification time.
+* `touch :r, "reffile"` -- uses timestamp of `reffile` instead of current timestamp.
+
+
+
+`chmod`
+-------
+
+* `chmod 0644, "x"` changes file permission.
+* `chmod :R, "a+r", "dir"` changes permissions recursively.
+* Permission can be `0644` sytle, or `u+w` style.
+
+<!--
+File: ex-chmod1.rb
+-->
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+## change permissions of files.
+chmod 0644, "file*.txt"
+chmod "a+r", "file*.txt"
+
+## change permissions recursively.
+chmod :R, 0644, "dir"
+chmod :R, "a+r", "dir"
+```
+
+Optionns:
+
+* `chmod :R` -- changes permissions recursively.
+
+
+
+`chown`
+-------
+
+* `chown "user:group", "x", "y"` changes owner and group of files.
+* `chown "user", "x", "y"` changes owner of files.
+* `chown ":group", "x", "y"` changes group of files.
+* `chown :R, "user:group", "dir"` changes owner and group recursively.
+
+<!--
+File: ex-chown1.rb
+-->
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+## change owner and/or group.
+chown "user1:group1", "file*.txt"     # change both owner and group
+chown "user1",        "file*.txt"     # change owner
+chown ":group1",      "file*.txt"     # change group
+```
+
+Optionns:
+
+* `chown :R` -- changes owner and/or group recursively.
+
+
+
+`pwd`
+-----
+
+* `pwd()` prints current working directory path.
+
+<!--
+File: ex-pwd1.rb
+-->
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+## prints current working directory
+pwd()
+```
+
+Options:
+
+* (no options)
+
+
+
+`store`
+-------
+
+* `store "x", "y", to: "dir", ` copies files under `x` and `y` to `dir` keeping file path.
+  For example, `x/foo/bar.rb` will be copied as `dir/x/foo/bar.rb`.
+* `store!` overwrites existing files while `store` doesn't.
+
+<!--
+File: ex-store1.rb
+-->
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+## copies files into builddir, keeping file path
+store "lib/**/*.rb", "test/**/*.rb", to: "builddir"
+```
+
+Options:
+
+* `store :p` -- preserves timestamps, permission, file owner and group.
+* `store :l` -- creates hard link instead of copying file.
+* `store :f` -- ignores non-existing files.
+
+
+
+`sys`
+-----
+
+* `sys "ls -al"` runs `ls -al` command.
+* `sys` raises error when command failed.
+* `sys!` ignores error even when command failed.
+* `sys` and `sys!` return `Process::Status` object regardless of command result.
+* `sys` and `sys!` can take a block argument as error handler called only when command failed.
+  If result of block argument is truthy, error will not be raised.
+
+<!--
+File: ex-sys1.rb
+-->
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+## run `ls` command
+sys "ls foo.txt"     # may raise error when command failed
+sys! "ls foo.txt"    # ignore error even when command filed
+
+## error handling
+sys "ls /fooobarr" do |stat|  # block called only when command failed
+  p stats.class       #=> Process::Status
+  p stat.exitstatus   #=> 1 (non-zero)
+  true                # suppress raising error
+end
+```
+
+Options:
+
+* (no options)
+
+
+
+`ruby`
+------
+
+* `ruby "...."` is almost same as `sys "ruby ...."`.
+* `RbConfig.ruby` is used as ruby command path.
+* `ruby` raises error when ruby command failed.
+* `ruby!` ignores error even when ruby command failed.
+
+<!--
+File: ex-ruby1.rb
+-->
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+## run ruby command
+ruby "file1.rb"      # raise error when ruby command failed
+ruby! "file1.rb"     # ignore error even when ruby command filed
+```
+
+Options:
+
+* (no options)
+
+
+
+`capture2`
+----------
+
+* `capture2 "ls -al"` runs `ls -al` and returns output of the command.
+* `capture2 "cat -n", stdin_data: "A\nB\n"` run `cat -n` command and uses `"A\nB\n"` as stdin data.
+* `caputre "ls foo"` will raise error when command failed.
+* `caputre! "ls foo"` ignores error even when command failed, and returns command output and process status object.
+* `capture2()` invokes `Popen3.capture2()` internally. All keyword arguments are available.
+
+<!--
+File: ex-capture2.rb
+-->
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+## run command and get output of the command.
+output = capture2 "ls -l foo.txt"                  # error if command failed
+output, process_status = capture2 "ls -l foot.xt"  # ignore error even command failed
+puts process_status.exitstatus
+
+## run command with stdin data.
+input = "AA\nBB\nCC\n"
+output = capture2 "cat -n", stdin_data: input
+```
+
+Options:
+
+* see [`Popen3.capture2()` manual page](https://docs.ruby-lang.org/en/master/Open3.html#method-c-capture2).
+
+
+
+`capture2e`
+-----------
+
+* almost same as `capture2`, but output contains both stdout and stderr.
+
+<!--
+File: ex-capture2e.rb
+-->
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+## run command and get output of the command, including stderr.
+output = capture2e "time ls -al"
+output, process_status = capture2e! "time ls -al"  # ignore error even command failed
+puts process_status.exitstatus
+```
+
+Options:
+
+* see [`Popen3.capture2e()` manual page](https://docs.ruby-lang.org/en/master/Open3.html#method-c-capture2e).
+
+
+
+`capture3`
+----------
+
+* almost same as `capture3`, but returns both stdout output and stderr output.
+
+<!--
+File: ex-capture3.rb
+-->
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+## run command and get output of both stdout and stderr separately
+output, error = capture3 "time ls -al"
+output, error, process_status = capture3! "time ls -al"  # ignore error even command failed
+puts process_status.exitstatus
+
+## run command with stdin data.
+input = "AA\nBB\nCC\n"
+output, error = capture3 "cat -n", stdin_data: input
+```
+
+Options:
+
+* see [`Popen3.capture3()` manual page](https://docs.ruby-lang.org/en/master/Open3.html#method-c-capture3).
+
+
+
+`zip`
+-----
+
+* `zip "foo.zip", "file1", "file2"` creates new zip file `foo.zip`.
+* `zip :r, "foo.zip", "dir1"` adds files under `dir1` into zip file recursively.
+* `zip` will be error if zip file already exists.
+* `zip!` will overwrite existing zip file.
+* `zip :'0'` doesn't compress files.
+* `zip :'1'` compress files in best speed.
+* `zip :'9'` compress files in best compression level.
+* `zip` and `zip!` requires `rubyzip` gem. You must install it by yourself.
+* `zip` and `zip!` doesn't support absolute path.
+
+<!--
+File: ex-zip1.rb
+-->
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+## create zip file
+zip "foo.zip", "file*.txt"            # requires 'rubyzip' gem
+
+## create zip file, adding files under directory
+zip :r, "foo.zip", "dir1"
+
+## create high-compressed zip file
+zip :r9, "foo.zip", "dir1"
+```
+
+Options:
+
+* `zip :r` -- adds files under directory into zip file recursively.
+* `zip :'0'` -- not compress files.
+* `zip :'1'` -- compress files in best speed.
+* `zip :'9'` -- compress files in best compression level.
+
+
+
+`unzip`
+-------
+
+* `unzip "foo.zip"` extracts files in zip file into current directory.
+* `unzip :d, "dir1", "foo.zip"` extracts files under `dir1`.
+  Diretory `dir1` should not exist or should be empty.
+* `unzip "foo.zip"` will be error if extracting file already exists.
+* `unzip! "foo.zip"` will overwrite existing files.
+* `unzip "foo.txt", "file1", "file2"` extracts only `file1` and `file2`.
+* `zunip` and `unzip!` requires `rubyzip` gem. You must install it by yourself.
+* `unzip` and `unzip!` doesn't support absolute path.
+
+<!--
+File: ex-unzip1.zip
+-->
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+## extracts zip file
+unzip "foo.zip"                # requires 'rubyzip' gem
+
+## extracts files in zip file into the directory.
+unzip :d, "dir1", "foo.zip"    # 'dir1' should be empty, or should not exist
+
+## overwrites existing files.
+unzip! "foo.zip"
+```
+
+Options:
+
+* `unzip :d, "dir1"` -- extracts files into the directory.
+
+
+
+`time`
+------
+
+* `time do ... end` invokes block and prints elapsed time into stderr.
+
+File: ex-time1.rb
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+time do
+  sh "zip -qr9 dir1.zip dir1"
+end
+```
+
+Result:
+
+```termianl
+[localhost]$ ruby ex-time1.rb
+$ zip -qr9 dir1.zip dir1
+
+        1.511s real       1.501s user       0.006s sys
+```
+
+
+
+FAQ
+====
+
+
+
+Why `mv` or `cp` requires `to:` option?
+---------------------------------------
+
+Because UNIX command has bad interface which causes unexpected result.
+
+For example, `mv` command of UNIX has two function: **rename** and **move**.
+
+* rename: `mv foo bar` (if `bar` is a file or not exist)
+* move: `mv foo bar` (if directory `bar` already exists)
+
+Obviously, rename function and move function are same form.
+This causes unexpected result easily due to, for example, typo.
+
+```terminal
+### Assume that you want rename 'foo' file to 'bar'.
+### But if 'bar' exists as directory, mv command moves 'foo' into 'bar'.
+### In this case, mv command should be error.
+$ mv foo bar
+```
+
+To avoid this unexpected result, `mv()` command of Benry::UnixCommand handles two functions in different forms.
+
+* rename: `mv "foo", "bar"` (error if directory `bar` exists)
+* move: `mv "foo", to: "bar"` (error if 'bar' is a file or not exist)
+
+In the same reason, `cp()` and `ln()` of Benry::UnixCommand also requires `to:` option.
+
+
+
+How to use in Rakefile?
+-----------------------
+
+File: Rakefile
+
+```ruby
+require 'benry/unixcmd'      # !!!!!
+include Benry::UnixCommand   # !!!!!
+Rake::DSL.prepend Benry::UnixCommand  # !!!!!
+
+task :example do
+  mkdir :p, "foo/bar/baz"
+  here = Dir.pwd()
+  pushd "foo/bar/baz" do
+    output = capture2 "pwd"
+    puts output.sub(here+"/", "")
+  end
+end
+```
+
+Result:
+
+```terminal
+[localhost]$ rake example
+$ mkdir -p foo/bar/baz
+$ pushd foo/bar/baz
+$  pwd
+foo/bar/baz
+$ popd    # back to /home/yourname
+```
+
+
+
+How to change prompt string?
+----------------------------
+
+File: ex-prompt1.rb
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+def prompt()                  # !!!!!
+  "myname@localhost>"         # !!!!!
+end                           # !!!!!
+
+sh "date"
+```
+
+Result:
+
+```terminal
+[localhost]$ ruby ex-prompt1.rb
+myname@localhost> date
+Wed Jan 15 20:23:07 UTC 2021
+```
+
+
+
+How to make prompt colored?
+---------------------------
+
+<!--
+File: ex-prompt2.rb
+-->
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+def prompt()
+  s = "myname@localhost>"
+  "\e[0;31m#{s}\e[0m"    # red
+  #"\e[0;32m#{s}\e[0m"    # green
+  #"\e[0;33m#{s}\e[0m"    # yellow
+  #"\e[0;34m#{s}\e[0m"    # blue
+  #"\e[0;35m#{s}\e[0m"    # magenta
+  #"\e[0;36m#{s}\e[0m"    # cyan
+  #"\e[0;37m#{s}\e[0m"    # white
+end
+
+sh "date"
+```
+
+
+
+How to disable command echoback?
+--------------------------------
+
+File: ex-quiet1.rb
+
+```ruby
+require 'benry/unixcmd'
+include Benry::UnixCommand
+
+BENRY_ECHOBACK = false            # !!!!!
+
+sh "date"
+```
+
+Result:
+
+```terminal
+$ ruby ex-quiet1.rb
+Wed Jan  1 22:29:55 UTC 2020      # no echoback, only output
+```
+
+
+
+License and Copyright
+=====================
+
+$License: MIT License $
+
+$Copyright: copyright(c) 2021 kuwata-lab.com all rights reserved $