@@ -299,17 +299,11 @@ _参考文献: [The Anti-Mac User Interface (Don Gentner and Jakob Nielsen)](htt
299
299
300
300
** なにもオプションを指定しなかった時、` -h ` や` --help ` フラグが指定された時にはヘルプテキストを表示してください。**
301
301
302
- <<<<<<< HEAD
303
302
** デフォルトでは簡潔なヘルプテキストを出力するようにしてください。**
304
- 可能なら、` myapp ` や` myapp subcommand ` が実行された時はデフォルトでヘルプテキストを表示するようにしてください。
305
- プログラムが非常にシンプルで明らかなデフォルトの動作があるとき (例: ` ls ` ) や、プログラムが入力をインタラクティブに受け取る時 (例: ` cat ` ) はその限りではありません。
306
- =======
307
- ** Display a concise help text by default.**
308
- When ` myapp ` or ` myapp subcommand ` is run with no arguments, display help text.
303
+ ` myapp ` や` myapp subcommand ` が引数なしで実行された時は、ヘルプテキストを表示してください。
309
304
310
- You can ignore this guideline if your program or subcommand is very simple and requires no arguments (e.g. ` ls ` , ` git pull ` ),
311
- or if it's interactive by default (e.g. ` npm init ` ).
312
- >>>>>>> upstream/main
305
+ プログラムが非常にシンプルで明らかなデフォルトの動作があるとき (例: ` ls ` 、` git pull ` ) や、
306
+ デフォルトでインタラクティブに動作するとき (例: ` npm init ` ) はこのガイドラインを無視しても構いません。
313
307
314
308
簡潔なヘルプテキストは以下のもののみを含むべきです。
315
309
@@ -551,13 +545,8 @@ _TTYが何かについては[参考文献を読んでください。](https://un
551
545
このテキストストリームは通常スクリプトを書くために使われますが、プログラムを使う人間のユーザビリティにも役立ちます。
552
546
たとえば、` grep ` に出力を流して期待する出力を得ることがあります。
553
547
554
- <<<<<<< HEAD
555
548
> “すべてのプログラムの出力は、未知のものも含めた他のプログラムの入力となることを期待する。”
556
- — [ Doug McIlroy] ( https://homepage.cs.uri.edu/~thenry/resources/unix_art/ch01s06.html )
557
- =======
558
- > “Expect the output of every program to become the input to another, as yet unknown, program.”
559
549
— [ Doug McIlroy] ( http://web.archive.org/web/20220609080931/https://homepage.cs.uri.edu/~thenry/resources/unix_art/ch01s06.html )
560
- >>>>>>> upstream/main
561
550
562
551
** 人間可読な出力が機械可読な出力を壊す場合、` --plain ` で出力を平易な、` grep ` や` awk ` のようなツールと統合できる表形式のテキストフォーマットにするようにしてください。**
563
552
場合によっては、人間にとって読みやすいのとは異なる方法で出力を行う必要があるかもしれません。
@@ -651,21 +640,12 @@ drwxr-xr-x 2 root root 4.0K Jul 20 14:57 skel
651
640
** プログラムがターミナルで動作していない、もしくはユーザが無効化するよう要請した時は、色を無効化してください。**
652
641
以下のようなもので色を無効化できるべきです。
653
642
654
- <<<<<<< HEAD
655
643
- ` stdout ` や` stderr ` がインタラクティブなターミナル (TTY) ではない。
656
644
この2つは個別にチェックするのが最良です。` stdout ` を他のプログラムにパイプ接続しているときでも、` stderr ` に色がついていると便利です。
657
- - ` NO_COLOR ` 環境変数が設定されている 。
645
+ - ` NO_COLOR ` 環境変数が設定されており、空でない(値は問いません) 。
658
646
- ` TERM ` 環境変数の値が` dumb ` である。
659
647
- ユーザが` --no-color ` オプションを渡した。
660
648
- 特にあなたのプログラムだけ色を無効化したいという場合は` MYAPP_NO_COLOR ` 環境変数を追加したくなるかもしれません。
661
- =======
662
- - ` stdout ` or ` stderr ` is not an interactive terminal (a TTY).
663
- It’s best to individually check—if you’re piping ` stdout ` to another program, it’s still useful to get colors on ` stderr ` .
664
- - The ` NO_COLOR ` environment variable is set and it is not empty (regardless of its value).
665
- - The ` TERM ` environment variable has the value ` dumb ` .
666
- - The user passes the option ` --no-color ` .
667
- - You may also want to add a ` MYAPP_NO_COLOR ` environment variable in case users want to disable color specifically for your program.
668
- >>>>>>> upstream/main
669
649
670
650
_ 参考文献: [ no-color.org] ( https://no-color.org/ ) , [ 12 Factor CLI Apps] ( https://medium.com/@jdxcode/12-factor-cli-apps-dd3c227a0e46 ) _
671
651
@@ -707,17 +687,10 @@ UwlHnUFXgENO3ifPZd8zoSKMxESxxot4tMgvfXjmRp5G3BGrAnonncE7Aj11pn3SSYgEcrrn2sMyLGpV
707
687
** 少なくともデフォルトでは` stderr ` をログファイルのように扱わないでください。**
708
688
verboseモードでない時にログレベルのラベル (` ERR ` 、` WARN ` 等) や関連性の薄い情報を出力しないでください。
709
689
710
- <<<<<<< HEAD
711
690
** 大量のテキストを出力する時はページャ (例: ` less ` ) を使ってください。**
712
691
たとえば、` git diff ` はデフォルトでこれを行います。
713
692
ページャの使用は問題を起こしやすいので、ユーザの体験を損なわないように実装には気をつけてください。
714
- ` stdin ` や` stdout ` がインタラクティブなターミナルでないならページャを使うべきではありません。
715
- =======
716
- ** Use a pager (e.g. ` less ` ) if you are outputting a lot of text.**
717
- For example, ` git diff ` does this by default.
718
- Using a pager can be error-prone, so be careful with your implementation such that you don’t make the experience worse for the user.
719
- Use a pager only if ` stdin ` or ` stdout ` is an interactive terminal.
720
- >>>>>>> upstream/main
693
+ ` stdin ` や` stdout ` がインタラクティブなターミナルである場合のみページャを使うようにしてください。
721
694
722
695
` less ` に対する優れたオプション指定は` less -FIRX ` です。
723
696
これによってコンテンツがスクリーンに収まる場合は動作せず、検索の際に大文字・小文字を無視し、色と書式を有効化し、` less ` が終了した時に画面にコンテンツを残すようになります。
@@ -874,31 +847,17 @@ unknown flag: --foo
874
847
これはユーザを混乱させるかもしれません。コマンドの使用においてそのような混乱が起こる最も一般的な動作は、上キーを押して直近の呼び出しを取り出して、末尾にオプションを追加してまた実行するような場面です。
875
848
可能ならば、引数パーサの制約にぶつかったとしても、どちらの形式も等価であるようにしてください。
876
849
877
- <<<<<<< HEAD
878
850
** シークレットをフラグから直接読まないでください。**
879
851
` --password ` のような形でコマンドがシークレットを受け取るとき、引数の値は` ps ` の出力や場合によりシェルの履歴等から漏洩します。
880
852
さらに、この手のフラグはシークレットに対するセキュアでない環境変数の使用を招きます。
853
+ (環境変数は他のユーザに読まれたり、値がデバッグログに残ったりすることがよくあるため、セキュアではありません。)
881
854
882
855
` --password-file ` のようにセンシティブなデータをファイルからのみ受け取るか、` stdin ` から受け取ることを検討してください。
883
856
` --password-file ` フラグは、様々なコンテキストにおいてシークレットをこっそりと渡すことを可能にします。
884
857
885
858
(Bashでは` --password $(< password.txt) ` のようにファイルの内容を渡すことが可能です。
886
- このアプローチは ` ps ` の出力によってファイルの中身が漏洩する同じようなセキュリティリスクがあります 。
859
+ このアプローチには環境変数と同様のセキュリティリスクがあります 。
887
860
避けるべきです。)
888
- =======
889
- ** Do not read secrets directly from flags.**
890
- When a command accepts a secret, e.g. via a ` --password ` flag,
891
- the flag value will leak the secret into ` ps ` output and potentially shell history.
892
- And, this sort of flag encourages the use of insecure environment variables for secrets.
893
- (Environment variables are insecure because they can often be read by other users, their values end up in debug logs, etc.)
894
-
895
- Consider accepting sensitive data only via files, e.g. with a ` --password-file ` flag, or via ` stdin ` .
896
- A ` --password-file ` flag allows a secret to be passed in discreetly, in a wide variety of contexts.
897
-
898
- (It’s possible to pass a file’s contents into a flag in Bash by using ` --password $(< password.txt) ` .
899
- This approach has the same security as mentioned above.
900
- It’s best avoided.)
901
- >>>>>>> upstream/main
902
861
903
862
### インタラクティブ性 {#interactivity}
904
863
@@ -1135,19 +1094,11 @@ XDGベースディレクトリ仕様
1135
1094
** 設定パラメータを優先順位に従って適用してください。**
1136
1095
以下は設定パラメータの優先順位を高いものから順に並べたものです。
1137
1096
1138
- <<<<<<< HEAD
1139
1097
- フラグ
1140
1098
- 実行中のシェルの環境変数
1141
1099
- プロジェクトレベルの設定 (例: ` .env ` )
1142
1100
- ユーザレベル設定
1143
1101
- システムレベル設定
1144
- =======
1145
- - Flags
1146
- - The running shell’s environment variables
1147
- - Project-level configuration (e.g. ` .env ` )
1148
- - User-level configuration
1149
- - System wide configuration
1150
- >>>>>>> upstream/main
1151
1102
1152
1103
### 環境変数 {#environment-variables}
1153
1104
0 commit comments