湊川流、文章ビフォーアフター術②「状況を明確にする」

https://gyazo.com/3ae97eaff0e38fec6696772348347f93

目的：Git公式ドキュメントをわかりやすくしてみよう！

llminatoll.icon 今回は "git checkout -- <ファイル名>" の解説を自分なりに推敲してみようと思います

leaf.iconBefore（公式ドキュメント原文）

# ファイルへの変更の取り消し

benchmarks.rb に加えた変更が、実は不要なものだったとしたらどうしますか? 変更を取り消す (直近のコミット時点の状態、あるいは最初にクローンしたり最初に作業ディレクトリに取得したときの状態に戻す) 最も簡単な方法は? 幸いなことに、またもや git status がその方法を教えてくれます。先ほどの例の出力結果で、ステージされていないファイル一覧の部分を見てみましょう。

code:Command line

Changes not staged for commit:

(use "git add <file>..." to update what will be committed)

(use "git checkout -- <file>..." to discard changes in working directory)

modified: benchmarks.rb

とても明確に、変更を取り消す方法が書かれています (少なくとも、バージョン 1.6.1 以降の新しい Git ではこのようになります。もし古いバージョンを使用しているのなら、アップグレードしてこのすばらしい機能を活用することをおすすめします)。ではそのとおりにしてみましょう。

code:Command line

$ git checkout -- sample.txt

$ git status

On branch master

Changes to be committed:

(use "git reset HEAD <file>..." to unstage)

modified: README.txt

変更が取り消されたことがわかります。また、これが危険なコマンドであることも知っておかねばなりません。あなたがファイルに加えた変更はすべて消えてしまいます。変更した内容を、別のファイルで上書きしたのと同じことになります。そのファイルが不要であることが確実にわかっているとき以外は、このコマンドを使わないようにしましょう。単にファイルを片付けたいだけなら、次の章で説明する stash やブランチを調べてみましょう。一般にこちらのほうがおすすめの方法です。

引用元:Git公式ドキュメント「Git の基本 - 作業のやり直し」

leaf.iconAfter（推敲後）

# ファイルに加えた変更を元に戻す

あなたは、編集する必要がないファイル「sample.txt」を間違えて編集してしまったとします。

まだコミットはしていません。

このファイルを、直近のコミット状態に戻すにはどうしたらいいでしょうか？

その答えは$ git statusコマンドが教えてくれます！

$ git statusと打ち込み、ステージされていないファイル一覧の部分を見てみましょう。

code:Command line

$ git status

Changes not staged for commit:

(use "git add <file>..." to update what will be committed)

(use "git checkout -- <file>..." to discard changes in working directory)

modified: sample.txt

注目すべきはこの一文です。

use "git checkout -- <file>..." to discard changes in working directory

翻訳すると

作業ディレクトリの変更を破棄するには、　"git checkout -- <ファイル名>" 　というコマンドを打ってね

という意味です。

では、そのとおりに打ってみましょう。

code:Command line

$ git checkout -- sample.txt

さて、本当に sample.txt の変更は取り消せたのでしょうか？

code:Command line

$ git status

On branch master

Changes to be committed:

(use "git reset HEAD <file>..." to unstage)

modified: README.txt

おめでとうございます！見事、sample.txt の変更が取り消されていますね！

※注意

$ git checkout -- <ファイル名> を実行すると、あなたがファイルに加えた変更はすべて消えてしまいます。

直近のコミットの状態を上書きしたのと同じことになります。

そのファイルが不要であることが確実にわかっているとき以外は、このコマンドを使わないようにしましょう。

単にファイルを片付けたいだけなら、次の章で説明する stash や branch を使いましょう。

https://gyazo.com/66eb747349b9bf8f974227cfb4689a68

leaf.iconやったこと

①骨を抜き出して、推敲

骨を抜き出すについて、詳細は湊川流、文章ビフォーアフター術①「だから何？」をご参照ください

②状況を明確にする

原文

この文章を読んでいて、読者が疑問に思うであろう点は

benchmarks.rbってなんだろう？

コミットした後か、コミットする前か？

ということだと思います。

よって、

benchmarks.rb -> sample.txt

コミットする前の話であることを明確にする

このように修正しました。

さらに難しく見せてしまっている要素がこちら。

直近のコミット時点の状態に戻す

あるいは最初にクローンしたときに戻す

あるいは最初に作業ディレクトリに取得したときの状態に戻す

抜け漏れなく様々なパターンが押さえられています。

しかし、この段階で、読者にこれらすべてのパターンを理解させる必要があるでしょうか。

一度に理解すべきことが多すぎて、頭がパンクしてしまうでしょう。

よって、

直近のコミット時点の状態に戻す

今の段階では、このポイントだけ伝わればよいと判断しました。 ->　場合によっては詳細を捨てる

③注目すべき点をはっきり示す

▼原文

code:Command line

Changes not staged for commit:

(use "git add <file>..." to update what will be committed)

(use "git checkout -- <file>..." to discard changes in working directory)

modified: benchmarks.rb

とても明確に、変更を取り消す方法が書かれています。

ではそのとおりにしてみましょう。

……ん？

どの部分のこと？

そのとおりって、どのとおり？

そう思ったので、注目すべき点を次のような形で独立させてみました。

さらに日本語訳も付け加えました。

▼推敲後

code:Command line

$ git status

Changes not staged for commit:

(use "git add <file>..." to update what will be committed)

(use "git checkout -- <file>..." to discard changes in working directory)

modified: sample.txt

注目すべきはこの一文です。

use "git checkout -- <file>..." to discard changes in working directory

翻訳すると

作業ディレクトリの変更を破棄するには、　"git checkout -- <ファイル名>" 　というコマンドを打ってね

という意味です。

では、そのとおりに打ってみましょう。

code:Command line

$ git checkout -- sample.txt

④感情を表現してあげる。読み手を置いてけぼりにしない

読み手の感情を常に気にしながら書きます。

たとえば「この出力結果は、成功してハッピーなのか？失敗してガーンなのか？」という具合です。

特に、読み手が初心者の場合「それが嬉しいことなのか、悲しいことなのか」の判別がつかないことが多いです。置いてけぼりになってしまうのです。（上級者の解説ブログを読んでいて、皆さんもそんな気持ちになった経験はありませんか？）

置いてけぼり問題を解決するために、私は要所要所で感情を入れています。

例：

おめでとうございます！見事、sample.txt の変更が取り消されていますね！

leaf.icon所感

llminatoll.icon 今回は見出しをどう名付けるかが難しかった！

日本語ドキュメントで「ファイルへの変更の取り消し」と訳されている部分ですね。私は散々悩んで「ファイルに加えた変更を取り消す」と訳しました。

英語原文ではどんな言葉が使われているかというと

「Unmodifying a Modified File」

直訳すると「変更されたファイルを変更されていない状態にする」という意味ですね。

「Unmodifying」、つまり「Modifiedじゃなくする」っていうのは個人的にとても感覚的だと感じたのですが、日本語としておかしいので、どうしても無理やり翻訳するしかありません。

そんな中、日本語ドキュメントの「変更の取り消し」という訳し方は素晴らしいと思いました。

他に、見出しの案としては「作業ディレクトリの変更を破棄する」というのも考えました。正確に内容を表していていいなと思ったのですが、初心者の方が読むという前提では「なんのためにそのコマンドを使うのか」という部分が抜けているのでよろしくないなと思ってセルフボツにしました。

何にせよ、膨大なドキュメントを正確さを失わないよう慎重に翻訳してくださっている方々は本当にすごいし、ありがたいことだなと、しみじみと思いました🙏　感謝llminatoll.icon

追記　2018/5/31

結城先生よりアドバイスいただきました！

https://gyazo.com/6c3dd2122933f298d71b202ec66b4412

「変更を戻す」わかりやすくていいですね！修正させていただきましたllminatoll.icon

ありがとうございます🙏✨llminatoll.icon

※諸注意

これは、湊川がどのように思考したか明文化しておくためのメモ書きで、随時更新されます。

引用元の文章に対する批判ではありません。単に個人のトレーニングのための題材として引用させていただいています。

「わかりやすい文章」は、人の数ほど/目的の数ほど正解があります。皆さんも一緒にレッツ推敲！

推敲とはなんたるかを教えてくれる書籍

結城浩先生『数学文章作法　推敲編』

私が解説文を書くときのすべてのベースになっている本です。

以下の結城先生のツイートから、第1章が無料で読めます。

https://twitter.com/hyuki/status/924139631712411649