direnv

DIRENV-STDLIB 1 “2019” direnv 「利用者用マニュアル」

名称

direnv-stdlib - .envrc用の関数

処方

direnv stdlib

解説

標準ライブラリと呼ばれるbashスクリプトを出力します。以下のコマンドがスクリプトに含まれており、.envrcの文脈に読み込まれます。加えて、~/.config/direnv/direnvrcが存在するなら、このファイルも読み込みます。

標準ライブラリ

`has <コマンド>`

コマンドが使えるときは0を返します。そうでなければ1を返します。コマンドとは、PATH中のバイナリまたはシェル関数です。

例は次の通り。

if has curl; then
  echo "Yes we do"
fi

`expand_path <相対パス> [<相対元>]`

相対元 または現在ディレクトリに対して相対な 相対パス の絶対パスを出力します。

例は次の通り。

cd /usr/local/games
expand_path ../foo
# 出力：/usr/local/foo

`dotenv [<.envのパス>]`

現環境に「.env」ファイルを読み込みます。

`dotenv_if_exists [<.envパス>]`

現環境に「.env」ファイルを読み込みます。ただし、存在しているときに限ります。

`user_rel_path <絶対パス>`

可能なら 絶対パス を利用者にとっての相対パスへ変換します。

例は次の通り。

echo $HOME
# 出力：/home/user
user_rel_path /home/user/my/project
# 出力：~/my/project
user_rel_path /usr/local/lib
# 出力：/usr/local/lib

`find_up <ファイル名>`

現ディレクトリから / に至るまで探索し、ファイル名のパスを出力します。ファイルが見つからなかったときは1を返します。

例は次の通り。

cd /usr/local/my
mkdir -p project/foo
touch bar
cd project/foo
find_up bar
# 出力：/usr/local/my/bar

`source_env <ファイルパスまたはディレクトリパス>`

パスかファイル名を指定し、別の.envrcを呼び込みます。

補足：他の.envrcはセキュリティの枠組みで検査されません。

`source_env_if_exists <ファイル名>`

別の「.envrc」を読み込みます。ただしファイルが存在するときだけです。

補足：source_envとは対照的に、この機能はファイルへのパスを渡されたときのみ動作します。ディレクトリではありません。

例は次の通り。

source_env_if_exists .envrc.private

`env_vars_required <変数名> [<変数名> ...]`

環境に存在しないか空の値を持つすべての変数に対してエラーをログ出力します。
普通これはsource_envやsource_env_if_existsと組み合わせて使われます。

例は次の通り。

# .envrc.private によりトークンが提供されることを期待
source_env .envrc.private
# トークンが存在することを確認
env_vars_required GITHUB_TOKEN OTHER_TOKEN

`source_up [<ファイル名>]`

find_up コマンドで別の.envrcが見付かれば読み込みます。ファイルが見つからなければ1を返します。

補足：他の.envrcはセキュリティの枠組みで検査されません。

`source_up_if_exists [<ファイル名>]`

find_up コマンドで別の.envrcが見つかれば読み込みます。何も見つからなければ、何も起きません。

補足：他の.envrcはセキュリティの枠組みで検査されません。

`source_url <URL> <正統性のためのハッシュ>`

与えられたURLから別のスクリプトを読み込みます。読み込む前に、与えられた正統性のためのハッシュを使って、正統性を検査します。

正統性のためのハッシュの値を調べるには、direnv fetchurl <URL>を呼んで出力された伝文からハッシュを抽出してください。

詳しくはdirenv-fetchurl(1)もご参照ください。

`fetchurl <URL> [<正統性のためのハッシュ>]`

与えられたURLから取得し、ディスクに保存します。また、標準入力にパスの場所を出力します。

正統性のためのハッシュの引数が与えられたときは、スクリプトの正統性も検査します。

詳しくはdirenv-fetchurl(1)もご参照ください。

`direnv_apply_dump <ファイル>`

ファイルに保管されたdirenv dumpの出力を読み込みます。

`direnv_load [<コマンドにより生成されたダンプ出力>]`

引数のリスト をコマンドとして走らせることで生成された環境を適用します。これは、子プロセスの環境を適用するのに便利です――そのプロセスで「direnv dump」を走らせてその結果が direnv_load で包まれます。

例は次の通り。

direnv_load opam exec direnv dump

`PATH_add <パス>`

展開したパスをPATH環境変数に前置します。 PATHが新しいパスだけで置き換わるという、よくある誤りを防ぎます。

例は次の通り。

pwd
# 出力：/home/user/my/project
PATH_add bin
echo $PATH
# 出力：/home/user/my/project/bin:/usr/bin:/bin

`MANPATH_add <パス>`

展開されたパスをMANPATH環境変数に前置します。 man特有の発見的手法を取り扱います。

`path_add <変数名> <パス>`

PATH_addのような動作ですが、任意の変数名を対象とします。

`PATH_rm <パターン> [<パターン> ...]`

与えられたシェルパターンに合致するディレクトリを、PATH環境変数から除きます。残りのディレクトリの順序ば、結果のPATHで維持されます。

Bashのパターン構文： https://www.gnu.org/software/bash/manual/html\_node/Pattern-Matching.html

例は次の通り。

echo $PATH
# 出力：/dontremove/me:/remove/me:/usr/local/bin/:...
PATH_rm '/remove/*'
echo $PATH
# 出力：/dontremove/me:/usr/local/bin/:...

`load_prefix <接頭辞パス>`

与えられた 接頭辞パス について、よくあるパス変数を展開します。 ./configure --prefix=$prefix_path && make installを使って 接頭辞パス に何かをインストールしており、プロジェクトで使いたいときに便利です。

設定される変数は以下です。

CPATH
LD_LIBRARY_PATH
LIBRARY_PATH
MANPATH
PATH
PKG_CONFIG_PATH

例は次の通り。

./configure --prefix=$HOME/rubies/ruby-1.9.3
make && make install
# そして.envrcで次のようにします
load_prefix ~/rubies/ruby-1.9.3

`semver_search <ディレクトリ> <フォルダ接頭辞> <部分バージョン>`

セマンティックバージョニングによるバージョン番号 (X.Y.Z) のうち最大のものについて、ディレクトリを検索します。

例は次の通り。

$ tree .
.
|-- dir
    |-- program-1.4.0
    |-- program-1.4.1
    |-- program-1.5.0
$ semver_search "dir" "program-" "1.4.0"
1.4.0
$ semver_search "dir" "program-" "1.4"
1.4.1
$ semver_search "dir" "program-" "1"
1.5.0

`layout <種類>`

よくあるプロジェクトの配置を記述するために使われる、意味論的な発出処理です。

`layout go`

「$(direnv_layout_dir)/go」をGOPATH環境変数に加えます。また、「$PWD/bin」をPATH環境変数に加えます。

`layout julia`

JULIA_PROJECT環境変数を現在ディレクトリに設定します。

`layout node`

「$PWD/node_modules/.bin」をPATH環境変数に加えます。

`layout opam`

opam envにより環境変数を設定します。

`layout php`

「$PWD/vendor/bin」をPATH環境変数に加えます。

`layout perl`

perlのlocal::libで必要な環境変数を準備します。詳細は http://search.cpan.org/dist/local-lib/lib/local/lib.pm を参照。

`layout pipenv`

layout pythonと似ていますが、Pipenvを使って、同ディレクトリにあるPipfileからvirtualenvを構築します。パスはPIPENV_PIPFILE環境変数で上塗りできます。

なお、Pipenvを手動で呼び出すのとは異なり、自動で.envファイルから環境変数を読み込みません。この挙動をそのまま実行するには、dotenv .envを加えると良いでしょう。

`layout pyenv [<バージョン> ...]`

layout pythonと似ていますが、pyenvを使って指定されたPythonインタプリタのバージョンでvirtualenvを構築します。

複数のバージョンを空白で区切って指定できます。詳細はpyenvの文書をご参照ください。

`layout python [<pythonの実行ファイル>]`

$PWD/.direnv/python-$pythonのバージョン配下にvirtualenvの環境を作り、読み込みます。これにより、eggのプロジェクトの副フォルダへのインストールが強制されます。

違うpythonのバージョンを使いたいときは、pythonの実行ファイルを指定できます（例：layout python python3）。

なお、以前$PWD/.direnv/virtualenv配下にあったvirtualenvがあるときは、direnvにより再利用されます。

`layout python3`

layout python python3の早道です。

`layout ruby`

GEM_HOME環境変数を$PWD/.direnv/ruby/RUBY_VERSIONに設定します。これにより、全てのgemがプロジェクトの副フォルダへ強制的にインストールされます。 bundlerを使っている場合、bundle execの接頭辞を使う代わりに、そのまま呼び出せるようにラッパープログラムが作られます。

`use <プログラム名> [<バージョン>]`

外部の依存関係を環境に読み込むことを目的とした、意味論的なコマンドの発出機能です。

例は次の通り。

use_ruby() {
  echo "Ruby $1"
}
use ruby 1.9.3
# 出力：Ruby 1.9.3

`use julia <バージョン>`

指定されたJuliaのバージョンを読み込みます。 $JULIA_VERSIONSを使って、インストールされたJuliaのバージョンのあるディレクトリへのパスを指定しなければなりません。 $JULIA_VERSION_PREFIX（既定はjulia-）を使い、$JULIA_VERSIONS内のフォルダの接頭辞を上塗りできますが、省けます。 <バージョン>にちょうと合致するものが見つからなければ、検索が実行され、最新版が読み込まれます。

例 (.envrc) は次の通りです。

use julia 1.5.1   # $JULIA_VERSIONS/julia-1.5.1 を読み込みます
use julia 1.5     # $JULIA_VERSIONS/julia-1.5.1 を読み込みます
use julia master  # $JULIA_VERSIONS/julia-master を読み込みます

`use rbenv`

rbenvを読み込み、使えるrubyのラッパーをPATHへ加えます。

`use nix [...]`

nix-shellによる環境変数を読み込みます。

default.nixやshell.nixがあるとき、これらが既定で使われます。しかし、パッケージを直接指定することもできます（例：use nix -p ocaml）。

http://nixos.org/nix/manual/\#sec-nix-shell を参照

`use flake [<インストール可能な対象>]`

派生物の構築環境を読み込みます。 nix developと似ています。

既定で現在のフォルダにflake.nixのdevShell属性を読み込みます。あるいは、「nixpkgs#hello」のように「インストール可能な対象」を渡して、最新のnixpkgsからhelloパッケージの構築の依存関係を全て読み込みます。

なおflakesの機能は実験的フラグで隠されています。こちらは自分で有効にしなければなりません。 Flakesはまだ安定とされていません。

`use guix [...]`

guix shellから環境変数を読み込みます。

与えられた全ての引数がguix shellに渡されます。例えばuse guix helloとすると、helloパッケージを含む環境を準備します。 helloの依存関係のある環境を作るには、--developmentフラグを使います。すなわちuse guix --development helloです。他のオプションには--fileがあり、ファイルから環境を読み込めます。

https://guix.gnu.org/manual/en/guix.html\#Invoking-guix-shell を参照

`rvm [...]`

rvmをインストールしているときは、そのシェルとちょうど同じはたらきになるでしょう。

`use node [<バージョン>]`:

指定されたNodeJSのバージョンを環境へ読み込みます。

部分的なNodeJSのバージョン（つまり4.2など）が渡されたとき、曖昧合致が実行され、最も大きい、インストールされている、合致したバージョンが選択されます。

バージョンが渡されないとき、現在のディレクトリに.nvmrcファイルや.node-versionファイルがあれば、それを参照します。

環境変数は次の通りです。

$NODE_VERSIONS（必須）全てのインストールされたNodeのバージョンを含むフォルダを指します。フォルダは存在しなければなりません。
$NODE_VERSION_PREFIX（省略可能）［既定では「node-v」］既定のバージョンの接頭辞を上塗りします。

`use vim [<vimrcファイル>]`

指定されたvimスクリプト（または既定では.vimrc.local）をDIRENV_EXTRA_VIMRC環境変数へ前置します。

この変数はdirenv/direnv.vim拡張で認識されます。この拡張が見つかったとき、ファイルをディレクトリで開いた後に読み込みます。

`watch_file <パス> [<パス> ...]`

各ファイルをdirenvの監視リストに加えます。ファイルが変わったら、direnvは次のプロンプトで環境を再読込みします。

例 (.envrc) は次の通り。

watch_file Gemfile

`watch_dir <ディレクトリ>`

各ファイルをdirenvの再帰的な監視リストに加えます。そのディレクトリやその配下ディレクトリの中のファイルが変わったときは、direnvは次のプロンプトで環境を再読込みします。

例 (.envrc) は次の通り。

watch_dir src

`require_allowed <パス> [<パス> ...]`

direnv >= 2.38.0が要求されます

require_allowedコマンドを使っている.envrcについてファイルのリストが許可リストに追加されます。指定されたファイルの何れかが変更、削除、ないしリスト中の新規ファイルが出現すると、direnvによりdirenv allowを再実行することが要求されます。再実行により再びその環境が認可されます。これは、陽に許可したファイルの変更のみに効果があるようにすることで、安全性を上げるためのものです。この機能を使うべきdirenvの構成とは、固定ファイルからコードを実行する場合です（例えばpixiの起動スクリプトやnpmのpostinstallスクリプトです）。

例 (.envrc) は次の通り。

require_allowed pixi.toml pixi.lock

`direnv_version <最低バージョン>`

direnvのバージョンが少なくとも最低バージョンと同じくらい古いことを確認します。 .envrcを共有しており、利用者の環境が最新であることを確認するときに便利なことがあります。

`strict_env [<コマンド> ...]`

シェル拡張の厳密性を有効にします。こうすると .envrc の評価の文脈が、次のときに直ちに終了するようにします。

パイプライン中のコマンドのどれかがゼロでない終了状態を返し、if、while、untilの条件で扱われなければ、値の否定 (!) ないし真偽値（&&または||）の連鎖の一部を返します。
明示的に設定されなかったり（declareやlocalで）宣言されなかったりした変数が参照されたとき、

コマンドラインが後続するとき、厳密性はそのコマンドの間、適用されます。

例（スクリプト全体）は次の通りです。

strict_env
has curl

（コマンドの）例は次の通りです。

strict_env has curl

`unstrict_env [<コマンド> ...]`

シェル拡張の厳密性を無効にします。コマンドラインが後続するとき、厳密性はコマンドの間、適用されます。

例（スクリプト全体）は次の通りです。

unstrict_env
has curl

（コマンドの）例は次の通りです。

unstrict_env has curl

`on_git_branch [<ブランチ名>]`

gitリポジトリにあり、与えられたブランチ名のときは0を返します。ブランチ名がなければ、どのブランチにいても0を返します。 gitコマンドがインストールされていることが必須です。そうでなければ1を返します。

ブランチが指定されているとき、.git/HEADが監視されます。そのため、ブランチに入ったり出たりすると再読込が引き起こされます。

例 (.envrc) は次の通り。

if on_git_branch child_changes; then
  export MERGE_BASE_BRANCH=parent_changes
fi

if on_git_branch; then
  echo "Thanks for contributing to a GitHub project!"
fi

著作情報

こちらも参照

direnv(1), direnv.toml(1)

日本語訳について

この日本語訳の原文はdirenv-stdlib(1) man pageです。

本文書の使用許諾は原文に従います。翻訳の著作情報は以下の通りです。

This site is open source. Improve this page.

direnv

DIRENV-STDLIB 1 “2019” direnv 「利用者用マニュアル」

名称

処方

解説

標準ライブラリ

has <コマンド>

expand_path <相対パス> [<相対元>]

dotenv [<.envのパス>]

dotenv_if_exists [<.envパス>]

user_rel_path <絶対パス>

find_up <ファイル名>

source_env <ファイルパスまたはディレクトリパス>

source_env_if_exists <ファイル名>

env_vars_required <変数名> [<変数名> ...]

source_up [<ファイル名>]

source_up_if_exists [<ファイル名>]

source_url <URL> <正統性のためのハッシュ>

fetchurl <URL> [<正統性のためのハッシュ>]

direnv_apply_dump <ファイル>

direnv_load [<コマンドにより生成されたダンプ出力>]

PATH_add <パス>

MANPATH_add <パス>

path_add <変数名> <パス>

PATH_rm <パターン> [<パターン> ...]

load_prefix <接頭辞パス>

semver_search <ディレクトリ> <フォルダ接頭辞> <部分バージョン>

layout <種類>

layout go

layout julia

layout node

layout opam

layout php

layout perl

layout pipenv

layout pyenv [<バージョン> ...]

layout python [<pythonの実行ファイル>]

layout python3

layout ruby

use <プログラム名> [<バージョン>]

use julia <バージョン>

use rbenv

use nix [...]

use flake [<インストール可能な対象>]

use guix [...]

rvm [...]

use node [<バージョン>]:

use vim [<vimrcファイル>]

watch_file <パス> [<パス> ...]

watch_dir <ディレクトリ>

require_allowed <パス> [<パス> ...]

direnv_version <最低バージョン>

strict_env [<コマンド> ...]

unstrict_env [<コマンド> ...]

on_git_branch [<ブランチ名>]

著作情報

こちらも参照

日本語訳について

`has <コマンド>`

`expand_path <相対パス> [<相対元>]`

`dotenv [<.envのパス>]`

`dotenv_if_exists [<.envパス>]`

`user_rel_path <絶対パス>`

`find_up <ファイル名>`

`source_env <ファイルパスまたはディレクトリパス>`

`source_env_if_exists <ファイル名>`

`env_vars_required <変数名> [<変数名> ...]`

`source_up [<ファイル名>]`

`source_up_if_exists [<ファイル名>]`

`source_url <URL> <正統性のためのハッシュ>`

`fetchurl <URL> [<正統性のためのハッシュ>]`

`direnv_apply_dump <ファイル>`

`direnv_load [<コマンドにより生成されたダンプ出力>]`

`PATH_add <パス>`

`MANPATH_add <パス>`

`path_add <変数名> <パス>`

`PATH_rm <パターン> [<パターン> ...]`

`load_prefix <接頭辞パス>`

`semver_search <ディレクトリ> <フォルダ接頭辞> <部分バージョン>`

`layout <種類>`

`layout go`

`layout julia`

`layout node`

`layout opam`

`layout php`

`layout perl`

`layout pipenv`

`layout pyenv [<バージョン> ...]`

`layout python [<pythonの実行ファイル>]`

`layout python3`

`layout ruby`

`use <プログラム名> [<バージョン>]`

`use julia <バージョン>`

`use rbenv`

`use nix [...]`

`use flake [<インストール可能な対象>]`

`use guix [...]`

`rvm [...]`

`use node [<バージョン>]`:

`use vim [<vimrcファイル>]`

`watch_file <パス> [<パス> ...]`

`watch_dir <ディレクトリ>`

`require_allowed <パス> [<パス> ...]`

`direnv_version <最低バージョン>`

`strict_env [<コマンド> ...]`

`unstrict_env [<コマンド> ...]`

`on_git_branch [<ブランチ名>]`