diff --git a/01-basics.md b/01-basics.md new file mode 100644 index 0000000000..c7ec16717a --- /dev/null +++ b/01-basics.md @@ -0,0 +1,86 @@ +--- +title: 自動的なバージョン管理 +teaching: 5 +exercises: 0 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- 自動バージョン管理システムの利点を理解しましょう。 +- 自動バージョン管理システムの仕組みの基本を理解しましょう。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- バージョン管理とは何で、なぜそれを使うべきなのでしょうか? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +それではまず、どのようにしてバージョン管理システムが 「いつ」、「何」を、「誰」が編集したのかを記録・管理しているかを見ていきましょう。 +他の人と共同作業をしていなくても、 以下の状況に陥るより、自動的なバージョン管理を使うほうが大分良いはずです： + +![「高く、深く積み上げる」Jorge Cham 作、 https://www.phdcomics.com](fig/phd101212s.png){alt='Comic: a PhD student sends "FINAL.doc" to their supervisor, but after several increasingly intense and frustrating rounds of comments and revisions they end up with a file named "FINAL_rev.22.comments49.corrections.10.#@$%WHYDIDCOMETOGRADSCHOOL????.doc"'} + +皆さんもこんな経験をされたことがあるはずです。複数の、（それもほとんど 内容が同じの）文書のコピーを保存しておくのは馬鹿げたことです。 文書作成ソフトの中には、例えばMicrosoft Wordの[変更履歴](https://support.office.com/en-us/article/Track-changes-in-Word-197ba630-0f5f-4a8e-9a77-3712475e806a)、Google Docsの[バージョン履歴](https://support.google.com/docs/answer/190843?hl=en)、LibreOfficeの[変更の記録・表示](https://help.libreoffice.org/Common/Recording_and_Displaying_Changes)、こういった状況にある程度うまく対応できるものもあります。 + +バージョン管理システムは、基礎となるドキュメントを元に、 加えられた全ての変更点を記録していきます。 バージョン管理システムは、基礎となるドキュメントを元に、 +加えられた全ての変更点を記録していきます。ドキュメントの +進歩を記録していると考えてもらって構いません。変更点を最初の状況まで +戻してから、最新版になるまでの変更を一つずつ再現していくことができます。 + +![](fig/play-changes.svg){alt='変更は連続して保存されます'} + +「変更点」と「ドキュメント」を別々の物として考えてみると、基礎となるドキュメントに +異なる変更点を「再現」する事によって、結果的に違ったバージョンのドキュメントを +作る事が可能だという事が分かります。 例えば、下の図のように二人のユーザーが同じドキュメントに違った編集を加えた場合です。 + +![](fig/versions.svg){alt='異なるバージョンの保存ができます'} + +変更点の衝突（コンフリクト）が無ければ、二つ以上の違った変更点を基礎ドキュメントに加えることさえできます。 + +![](fig/merge.svg){alt='複数のバージョンをマージできます'} + +バージョン管理システムは、ユーザーがドキュメントに加えた変更点を記録するツールであり、 結果的にドキュメントの違ったバージョンを作成する事ができます。 このツールを活用 する事によって、次のバージョンに加える変更点（個々の変更点は 「[commit（コミット）](../learners/reference.md#commit)」と呼びます）を決める事ができ、変更点に関するメタデータも一緒に保存する事ができます。 特定のプロジェクトのコミット履歴とそれに関するメタデータを総じて 「[repository（リポジトリ）](\(../learners/reference.md#repository\))」と呼びます。 +リポジトリは 別々のコンピュータと同期させる事が出来るので、他人との共同作業を潤滑に進めることが可能になります。 + +::::::::::::::::::::::::::::::::::::::::: callout + +## バージョン管理システムの長い歴史 + +自動化されたバージョン管理システムは最近発明されたものではありません。 +[RCS](https://ja.wikipedia.org/wiki/Revision_Control_System)、[CVS](https://ja.wikipedia.org/wiki/Concurrent_Versions_System)、[Subversion](https://ja.wikipedia.org/wiki/Apache_Subversion)などのツールは1980年前半から存在しており、多くの会社に使われていました。 +しかし、これらのツールでは出来る事に制限があり、多くはもう時代遅れとされています。 +現代使われているシステム、例えばGitや[Mercurial](https://swcarpentry.github.io/hg-novice/)、は _分散_されています。というのは、特定のサーバーを必要とせずにシステムをホストする事が出来るという事です。 +現代のシステムには大変便利で効果的な「merge（マージ）」機能が備われており、同じファイルを 複数人で作業する事が可能になりました。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## 論文を書くにあたって + +- 例えば、論文のために数百行書いたとします。しばらくして、間違えてその文章を編集してしまいます。 どうしたら以前書いた文章を取り戻すことができるのでしょう？ そもそも、可能なのでしょうか？ + +- 五人の共著者がいるとします。 どうやって全員の変更やコメントを管理すれば良いのでしょう？ LibreOffice WriterやMicrosoft Wordの場合、こういった変更やコメントを変更履歴機能で受け入れると どうなるのでしょう？ 変更点は記録されるのでしょうか？ + +::::::::::::::: solution + +## 解答 + +- 以前書いた数百行の回復は、古いバージョンの論文のコピーを作成した場合にのみ可能です。 前に書いた文章を失う危険性は、このページの上にある漫画に描かれているような問題のあるワークフローになることが多いです。 + +- 従来のワープロを使った共同執筆は面倒です。 + すべての共同作業者が文書に順番に書く（執筆のプロセスを遅らせる）か、一つのバージョンをすべての全員に送り、手作業で彼らのコメントをあなたの文書にマージしなければなりません。 「変更の追跡」または「変更の記録」オプションは、変更をハイライトし、マージを簡略化することができますが、変更を受け入れるとすぐにその履歴が失われます。 そうなると、誰がその変更を提案したのか、なぜそれが提案されたのか、いつ文書にマージされたのか、わからなくなります。 + Google DocsやMicrosoft Office Onlineのようなオンライン・ワープロでさえ、こうした問題を完全に解決することはできません。 + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- バージョン管理とは、制限無く「元に戻す」ことができる機能。 +- バージョン管理を使えば、複数の人と同時進行で作業をする事ができます。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/02-setup.md b/02-setup.md new file mode 100644 index 0000000000..928e7be902 --- /dev/null +++ b/02-setup.md @@ -0,0 +1,194 @@ +--- +title: Gitの設定 +teaching: 5 +exercises: Vim の終了の仕方 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- コンピュータで初めて `git` を使うための設定が出来るようになりましょう。 +- `--global` 設定フラグの意味を理解しましょう。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- Git を使うために必要な設定は何ですか？ + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +Git を新しいパソコンで初めて使う場合、いくつかの設定を変更しなければなりません。 Git を始めるにあたって、私達が変更する設定をいくつか表記します： + +- 名前とメールアドレス、 +- 使用したいテキストエディタ、 +- 以上の設定をグローバル設定として使う（つまり、全てのプロジェクトに反映させる）。 + +コマンドラインでは、Git コマンドは `git <動詞> <オプション>` と入力します。ここでの「動詞」は、Git に何をさせたいのかを表し、「オプション」はその動詞にとって必要とされる追加の情報です。 ドラキュラが新しいユーザーの場合、以下のようにコンピュータを設定します： + +```bash +Vim の終了の仕方 +``` + +ここでは、ドラキュラの代わりに自分の名前とメールアドレスを使いましょう。 ここで入力した名前とメールアドレスは、これから行う Git での作業に関わってきます。というのも、これからのレッスンで[GitHub](https://github.com/)、[BitBucket](https://bitbucket.org/)、[GitLab](https://gitlab.com/)、またはその他のGit をホストするサーバーに変更箇所を「プシュ」した（送った）際に、これらの情報が使われるからです。 + +これらのレッスンでは、[GitHub](https://github.com/) に接続するので、GitHub アカウントと同じメールアドレスに設定してください。 プライバシーについて気になる方は、[GitHub のメールアドレスをプライベートにするための説明][git-privacy] を参照してください。 + +::::::::::::::::::::::::::::::::::::::::: callout + +## 電子メールの非公開 + +GitHub でプライベートのメールアドレスを使う場合は、同じメールアドレスを `user.email` の値に設定してください（例：`username@users.noreply.github.com`）。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::::: callout + +## 改行コード + +他のキーと同様に、キーボードで Enter または ↵ （またはMacでは Return）を押すと、コンピュータはそれを文字として入力します。 +話が長くなるので詳しい説明は省きますが、行末に使われる文字はオペレーティングシステム（OS）よって違います。 +（行末に使われる文字を「改行コード」と呼びます。） +Git は、改行コードを使ってファイルの違いを確かめるため、違うパソコンでファイルを編集した時に思わぬ問題が起こるかもしれません。 +このレッスンの範囲外ですが、この問題については +[Pro Git book](https://www.git-scm.com/book/en/v2/Customizing-Git-Git-Configuration#_core_autocrlf) を読んでください。 + +Git がどのように改行コードを理解・変換するかは、 `git config` の `core.autocrlf` コマンドを使って変更できます。 +以下の設定をおすすめします： + +macOS および Linux: + +```bash +$ git config --global core.autocrlf input +``` + +またはWindowsの場合: + +```bash +$ git config --global core.autocrlf true +``` + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +以下の表を参考に、ドラキュラはテキストエディタも設定しました： + +| エディタ | 設定コマンド | +| :------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------- | +| Atom | `$ git config --global core.editor "atom --wait"` | +| nano | `$ git config --global core.editor "nano -w"` | +| BBEdit（Mac、コマンドラインツール付き） | `$ git config --global core.editor "bbedit -w"` | +| Sublime Text (Mac) | `$ git config --global core.editor "/Applications/Sublime\ Text.app/Contents/SharedSupport/bin/subl -n -w"` | +| Sublime Text (Win、32ビットインストール) | `$ git config --global core.editor "'c:/program files (x86)/sublime text 3/sublime_text.exe' -w"` | +| Sublime Text (Win、64ビットインストール) | `$ git config --global core.editor "'c:/program files/sublime text 3/sublime_text.exe' -w"` | +| メモ帳（Win） | `$ git config --global core.editor "c:/Windows/System32/notepad.exe"` | +| Notepad++ (Win、 32 ビットインストール) | `$ git config --global core.editor "'c:/program files (x86)/Notepad++/notepad++.exe' -multiInst -notabbar -nosession -noPlugin"` | +| Notepad++ (Win、 64 ビットインストール) | `$ git config --global core.editor "'c:/program files/Notepad++/notepad++.exe' -multiInst -notabbar -nosession -noPlugin"` | +| Kate (Linux) | `$ git config --global core.editor "kate"` | +| Gedit (Linux) | `$ git config --global core.editor "gedit --wait --new-window"` | +| Scratch (Linux) | `$ git config --global core.editor "scratch-text-editor"` | +| Emacs | `$ git config --global core.editor "emacs"` | +| Vim | `$ git config --global core.editor "vim"` | +| VS Code | `$ git config --global core.editor "code --wait"` | + +設定したテキストエディタもいつでも変更することができます。 + +::::::::::::::::::::::::::::::::::::::::: callout + +## Vim の終了の仕方 + +多くのソフトの初期設定では、Vim がデフォルトのテキストエディタに設定されています。 保存せずに Vim を終了するには、Escを押した後に `:q!` と入力してからEnterまたは↵（Macの場合はReturn）を押してください。 +保存してから終了するには、Escを押してから `:wq` と入力してEnterまたは↵（Mac の場合は Return）を押してください。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +Git (2.28以上) では、新しいリポジトリを初期化したときに作成されるブランチの名前を設定できます。 ドラキュラはその機能を使って、最終的に使うクラウドサービスと一致するように`main`に設定することにします。 + +```bash +$ git config --global init.defaultBranch main +``` + +::::::::::::::::::::::::::::::::::::::::: callout + +## Gitブランチ名の設定 + +ソースファイルのどんな変更でも、ある「ブランチ」に属しています。 +このレッスンの新しい学習者にとっては、ブランチが存在し、このレッスンでは1つのブランチを使うことを知っていれば十分です。\ +デフォルトでは、`git init` で新しいリポジトリを作成すると、Git が`master` +というブランチを作成します (次のエピソードで説明します)。 この用語は、 +人身売買という人種差別的慣習を想起させ、 +[ソフトウェア開発コミュニティ](https://github.com/github/renaming) は、 +より包括的な言葉を採用するように動いています。 + +2020年には、ほとんどのGit ホスティングサービスは、`main`をデフォルトの +ブランチとして使うように移行しました。 例として、GitHub やGitLab で新規に開いたリポジトリのデフォルトは +`main`です。 しかし、Gitはまだ同じ変更を行っていません。 その結果、ローカル・リポジトリは、ほとんどのクラウド・サービスと同じブランチ名を手動で設定する必要があります。 + +2.28より前のバージョンのGitでは、個々のリポジトリで変更が可能です。 そのためのコマンドは次回のエピソードで紹介します。 ローカルのGit の設定でこの値が設定されていない場合、`init.defaultBranch` のデフォルト値は `master` になることに注意しましょう。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +上記の5つのコマンドは、一度実行するだけで十分です。`--global` フラグは Git に、 +今使っているパソコン内にある自分のアカウントに関連する全てのプロジェクトに同じ設定をするように指示しています。 + +さっそくこれらの設定を確認し、`core.editor`をテストしてみましょう： + +```bash +$ git config --global --edit +``` + +追加の変更を加えずにファイルを閉じましょう。 設定ファイルのタイプミスは問題を引き起こすため、以下のように設定を表示する方が安全です。 + +```bash +$ git config --list +``` + +また、必要であれば、同じコマンドを使えば、違うエディタやメールアドレスに変えることができます。 +これは何度でもできます。 + +::::::::::::::::::::::::::::::::::::::::: callout + +## プロキシ + +ネットワーク環境によっては[プロキシ](https://ja.wikipedia.org/wiki/%E3%83%97%E3%83%AD%E3%82%AD%E3%82%B7) を使わなければならないかもしれません。 この場合、プロキシの設定が必要です： + +```bash +$ git config --global http.proxy proxy-url +$ git config --global https.proxy proxy-url +``` + +プロキシを無効にするには： + +```bash +$ git config --global --unset http.proxy +$ git config --global --unset https.proxy +``` + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::::: callout + +## Git のヘルプとマニュアル + +`git` のコマンドを忘れた時は、`-h` を使えばコマンドの一覧を、`--help` を使えばマニュアルを見ることができます：ある `git` コマンドのサブコマンドやオプションを忘れてしまった場合は、 `git -h` とタイプすることによって関連するオプションのリストを見るか、`git --help` とタイプすることによって対応する Git マニュアルを見ることができます： + +```bash +$ git config -h +$ git config --help +``` + +マニュアルを見ている間、`:`はコマンドを待っているプロンプトであり、 Q を押してマニュアルを終了できることを覚えておいてください。 + +より一般的には、利用可能な `git` コマンドのリストや、Git マニュアルを入手することができます： + +```bash +$ git help +``` + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +[git-privacy]: https://help.github.com/articles/keeping-your-email-address-private/ + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- `git config` と `--global` オプションを使い、ユーザー名、メールアドレス、エディタ、その他の設定を行う。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/03-create.md b/03-create.md new file mode 100644 index 0000000000..2273748035 --- /dev/null +++ b/03-create.md @@ -0,0 +1,180 @@ +--- +title: リポジトリの作成 +teaching: 10 +exercises: 0 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- ローカルのGitリポジトリを作成する。 +- `.git` ディレクトリの目的を説明する。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- Gitはどこに情報を格納しますか? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +Gitの設定ができたら、 +それを使い始めることができます。 + +火星に惑星着陸船を送ることが可能かどうかを調査しているウルフマンとドラキュラの話に戻りましょう。 + +![](fig/motivatingexample.png){alt='motivatingexample'} +[ウルフマン対ドラキュラ](https://www.deviantart.com/b-maze/art/Werewolf-vs-Dracula-124893530) +by [b-maze](https://www.deviantart.com/b-maze) / [Deviant Art](https://www.deviantart.com/). +[火星](https://en.wikipedia.org/wiki/File:OSIRIS_Mars_true_color.jpg) by European Space Agency / +[CC-BY-SA 3.0 IGO](https://creativecommons.org/licenses/by/3.0/deed.en). +[冥王星](https://commons.wikimedia.org/wiki/File:PIA19873-Pluto-NewHorizons-FlyingPastImage-20150714-transparent.png) / +Courtesy NASA/JPL-Caltech. +[ミイラ](https://commons.wikimedia.org/wiki/File:Mummy_icon_-_Noun_Project_4070.svg) +© Gilad Fried / [The Noun Project](https://thenounproject.com/) / +[CC BY 3.0](https://creativecommons.org/licenses/by/3.0/deed.en). +[月](https://commons.wikimedia.org/wiki/File:Lune_ico.png) +© Luc Viatour / [https://lucnix.be](https://lucnix.be/) / +[CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/deed.en). + +まず、`Desktop`フォルダーに作業用のディレクトリを作成し、そのディレクトリに移動しましょう: + +```bash +$ cd ~/Desktop +$ mkdir planets +$ cd planets +``` + +次に、Gitに`planets`を[リポジトリ](../learners/reference.md#repository)（Gitがファイルのバージョンを保存できる場所）にするように伝えます。 + +```bash +$ git init +``` + +重要なのは、`git init` はサブディレクトリとそのファイルを含むことができるリポジトリを作成するということです。サブディレクトリが最初から存在する場合でも、後から追加された場合でも、`planets` リポジトリの中に入れ子になった別のリポジトリを作成する必要はありません。 また、 `planets`ディレクトリの作成と、リポジトリとしての初期化はまったく別の処理であることに注意してください。 + +`ls` を使ってディレクトリの内容を表示すると、 +何も変更されていないように見えます: + +```bash +$ ls +``` + +ですが `-a` フラグを追加してすべてを表示すると、Git が `.git`という隠しディレクトリを `planets` の中に作ったことがわかります: + +```bash +$ ls -a +``` + +```output +. .. .git +``` + +Git はプロジェクトのディレクトリ内にあるすべてのファイルとサブディレクトリを含む、プロジェクトに関するすべての情報を格納するためにこの特別なサブディレクトリを使用します。 +`.git` サブディレクトリを削除すると、プロジェクトの履歴を失うことになります。 + +次に、デフォルトのブランチを `main` という名前に変更します。 +あなたの設定やgitのバージョンによっては、これが既にデフォルトになっているかもしれません。 +この変更の詳細については、[「セットアップ」](02-setup.md#default-git-branch-naming) を参照してください。 + +```bash +$ git checkout -b main +``` + +```output +Switched to a new branch 'main' +``` + +プロジェクトのステータスをGitに問うことで、すべてが正しく設定されていることを確認できます: + +```bash +$ git status +``` + +```output +On branch main + +No commits yet + +nothing to commit (create/copy files and use "git add" to track) +``` + +使用している`git`のバージョンによって、出力の表現が少し異なるかもしれません。 + +::::::::::::::::::::::::::::::::::::::: challenge + +## Git リポジトリを作る場所 + +`planets` （すでに作成したプロジェクト）についての情報を追跡すると共に、 ドラキュラは moons についての情報も追跡したいと考えています。 +ウルフマンの心配にもかかわらず、ドラキュラは次の一連のコマンドを使って、彼の `planets`プロジェクト内に `moons` プロジェクトを作ります: + +```bash +$ cd ~/Desktop # Desktop ディレクトリに戻る +$ cd planets # すでに Git リポジトリである planets ディレクトリに移動する +$ ls -a # .git サブディレクトリがまだ planets ディレクトリに存在することを確認する +$ mkdir moons # サブディレクトリ planets/moons を作る +$ cd moons # moons サブディレクトリに移動する +$ git init # moons サブディレクトリをGitリポジトリにする +$ ls -a # .git サブディレクトリが存在し新しいGitリポジトリが作られたと示していることを確認する +``` + +`git init` コマンドは、`moons` サブディレクトリ内で実行され、`moons` サブディレクトリに保存されているファイルを追跡するために必要でしょうか? + +::::::::::::::: solution + +## 解答 + +いいえ。 ドラキュラは `moons` サブディレクトリを Git リポジトリにする必要はありません。`planets` リポジトリは、`planets` ディレクトリの下のすべてのファイル、サブディレクトリ、およびサブディレクトリファイルを追跡するからです。 従って、`moons` についてのすべての情報を追跡するのは、ドラキュラが `moons` サブディレクトリを`planets` ディレクトリに追加するだけで済みます。 + +それと、Git リポジトリが「入れ子」にされている場合、Gitリポジトリは互いに干渉する可能性があります：外側のリポジトリは内側のリポジトリのバージョン管理をしようとします。 したがって、新しいGitリポジトリはそれぞれ別のディレクトリに作るのがベストです。 ディレクトリに競合するリポジトリががないことを確認するには、`git status`の出力を確認します。 次のような場合は、上の方で示したように新しいリポジトリを作ることをお勧めします： + +```bash +$ git status +``` + +```output +fatal: Not a git repository (or any of the parent directories): .git +``` + +::::::::::::::::::::::::: + +## `git init` の間違いを修正する + +ウルフマンはドラキュラに、「入れ子」状態になっているリポジトリがいかに冗長で、混乱を引き起こす可能性があるかを説明しました。 説明を聞いて、ドラキュラは「入れ子」状態のリポジトリを削除したいと思いました。 `moons`サブディレクトリの最後の`git init`を、ドラキュラはどうやって、元に戻すことができるのでしょうか？ + +::::::::::::::: solution + +## 解決策 （要注意！） + +### 背景 + +Gitリポジトリからのファイルの削除は、慎重に行う必要があります。 しかし、特定のファイルを追跡するようにGitに指示する方法については、まだ学んでいません（次のエピソードで学びます）。 Gitによって追跡されていないファイルは、他の「普通の」ファイルと同じように、次のようにして簡単に削除できます： + +```bash +$ rm filename +``` + +同様に、`rm -r dirname` または `rm -rf dirname` を使ってディレクトリを削除することができます。 +この方法で削除されるファイルやフォルダがGitによって追跡されているなら、次のエピソードで見られるように、それらの削除が、追跡する必要がある別の変更になります。 + +### 解答 + +Gitはすべてのファイルを`.git`ディレクトリに保存します。 +この小さなミスから立ち直るには、ドラキュラは`planets`ディレクトリの中から次のコマンドを実行して、moonsサブディレクトリの中の`.git`フォルダを削除すれば良い： + +```bash +$ rm -rf moons/.git +``` + +しかし、気をつけてください！ 間違ったディレクトリでこのコマンドを実行すると、残しておきたいプロジェクトのGit履歴がすべて削除されてしまいます。 +したがって、常に `pwd` コマンドを使用してカレントディレクトリを確認してください。 + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- `git init` はリポジトリを初期化する。 +- Gitはリポジトリデータのすべてを`.git`ディレクトリに格納する。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/04-changes.md b/04-changes.md new file mode 100644 index 0000000000..bd8a64b362 --- /dev/null +++ b/04-changes.md @@ -0,0 +1,698 @@ +--- +title: 変更内容の記録 +teaching: 20 +exercises: 0 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- 一つ以上のファイルにおいて、「変更・追加・コミット」の作業を行いましょう。 +- 「変更・追加・コミット」を行っている際、情報がどこに保管されているのか説明しましょう。 +- わかりやすいコミットメッセージと、そうでないメッセージの違いを区別できるようになりましょう。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- どうやって変更点を Git で記録出来ますか？ +- どうやってリポジトリの状態をチェック出来ますか？ +- 何を変更して、なぜ変えたのかをメモするにはどうすればよいですか？ + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +まずはじめに、正しいディレクトリにいるかどうか確かめましょう。 +`planets` ディレクトリに入っているはずです。 + +```bash +$ cd ~/Desktop/planets +``` + +赤い惑星（火星）が基地に最適かどうかについてのノートを書くために`mars.txt` というファイルを作成しましょう。 +`nano` （もしくは好きなテキストエディタ）でファイルを編集しましょう。 +以前 `core.editor` で設定したエディタとは別のエディタで編集しても大丈夫です。 ですが、新しくファイルを作成・編集するコマンドはエディタによって違うということを覚えておいてください（`nano` ではないかもしれません）。 テキストエディタについて復習したい方は、[Unix シェル](https://swcarpentry.github.io/shell-novice/) の [どのエディタ？](https://swcarpentry.github.io/shell-novice/03-create/) のレッスンを見てみてください。 + +```bash +$ nano mars.txt +``` + +以下の文を `mars.txt` に記入してください： + +```output +Cold and dry, but everything is my favorite color +``` + +まず、listコマンド（`ls`）を実行して、ファイルが正しく作成されたことを確認しましょう： + +```bash +$ ls +``` + +```output +mars.txt +``` + +これで `mars.txt` は一文だけ入ってる状態になりました。確認してみましょう： + +```bash +$ cat mars.txt +``` + +```output +Cold and dry, but everything is my favorite color +``` + +プロジェクトの状態をもう一度確認してみると、 +Git は新しいファイルがあることに気づきます： + +```bash +$ git status +``` + +```output +On branch main + +No commits yet + +Untracked files: + (use "git add ..." to include in what will be committed) + + mars.txt + +nothing added to commit but untracked files present (use "git add" to track) +``` + +"untracked files" （追跡されていないファイル）というメッセージは、 +Git が追跡していないファイルがこのディレクトリに存在していることを意味します。 +`git add` を使って、Git にこのファイルを追跡してもらいましょう： +`git add` を使って、Git にこのファイルを追跡してもらいましょう： + +```bash +$ git add mars.txt +``` + +そして、正しく動作したか確認してみましょう： + +```bash +$ git status +``` + +```output +On branch main + +No commits yet + +Changes to be committed: + (use "git rm --cached ..." to unstage) + + new file: mars.txt + +``` + +これで Git は `mars.txt` を追跡するように設定することができました。 +ですが、まだ変更点をコミットとして記録していません。 +これをするには、もう一つコマンドを使う必要があります： + +```bash +$ git commit -m "Start notes on Mars as a base" +``` + +```output +[main (root-commit) f22b25e] Start notes on Mars as a base + 1 file changed, 1 insertion(+) + create mode 100644 mars.txt +``` + +`git commit` を使うと、 +Git は `git add` によって一時的に保存されたデータを +`.git` ディレクトリにコピー、そして永久保存します。 +永久保存されたコピーを [コミット](../learners/reference.md#commit) +（または [リビジョン](../learners/reference.md#revision))）と呼び、`f22b25e` はコミットの省略されたIDです。 あなたのコミットには別のIDが使われているかもしれません。 + +`-m` フラグ（「メッセージ」の略）を使い、何を変えて、なぜ変えたのかが後からでも分かるように、簡潔で分かりやすいメッセージを書きましょう。 +`-m` を使わずに `git commit` を使った場合、Git は `nano` （または `core.editor` として設定したエディタ）を開き、もっと長いメッセージを書くことができます。 + +[良いコミットメッセージ][commit-messages] は、どのような変更が行われたのかが分かる短い文（50字以下） +で始まります。 大抵のメッセージは、「このコミットを適用すると」という文が完全文になるように書かれます。 +もっと詳しく書きたい場合は、このメッセージの後に改行してからノートを加えましょう。 ここには、なぜこのような変更をしたのか、この変更によって何が影響を受けるかなどといった事を書くといいでしょう。 + +今の状態で `git status` を走らせると： + +```bash +$ git status +``` + +```output +On branch main +nothing to commit, working tree clean +``` + +といったように、最新の状態であることを教えてくれます。 +つい先程、何をしたのかを見たい場合は `git log` を使って、 Git にプロジェクトの履歴を表示してもらいましょう： + +```bash +$ git log +``` + +```output +commit f22b25e3233b4645dabd0d81e651fe074bd8e73b +Author: Vlad Dracula +Date: Thu Aug 22 09:51:46 2013 -0400 + + Start notes on Mars as a base +``` + +`git log` は、リポジトリに施された全てのコミットを最新のものから順に表示します。 +各コミットには、省略されていないコミットID（以前 `git commit` で表示された省略IDと同じ字列で始まります）、コミットの著者、作成日時、そして、コミットが作られた時につけられたログメッセージが含まれています。 + +::::::::::::::::::::::::::::::::::::::::: callout + +## 変更点は何処にあるの？ + +ここで `ls` を使用すると、`mars.txt` ファイル一つしかありません。 +なぜかと言うと、Git はファイルの変更履歴を、以前触れた `.git` という特別なディレクトリに保存します。これをする事によって、ファイルシステムが散らからないようにし、うっかり古いバージョンのファイルを変更、または削除できないようにしています。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +それでは、ドラキュラがファイルに新しい情報を加えたとしましょう。 +（以前と同様に、`nano` を使い、`cat` でファイルの中身を表示させます。違うエディタを使ってもいいし、`cat` を使わなくても構いません。） + +```bash +$ nano mars.txt +$ cat mars.txt +``` + +```output +Cold and dry, but everything is my favorite color +The two moons may be a problem for Wolfman +``` + +`git status` を使うと、追跡しているファイルが変更されたことを知らせてくれます： + +```bash +$ git status +``` + +```output +On branch main +Changes not staged for commit: + (use "git add ..." to update what will be committed) + (use "git checkout -- ..." to discard changes in working directory) + + modified: mars.txt + +no changes added to commit (use "git add" and/or "git commit -a") +``` + +最後に表示された文が一番重要です："no changes added to commit" （「変更点はコミットに追加されていません」）。 +私達はファイルを編集したのですが、まだ Git にこの変更点を保存したいということを（`git add` で）伝えていないし、それを（`git commit` で）保存もしていません。 +というわけで、これらをやってみましょう。 変更点を保存する前に見直すのは、習慣づけると良いでしょう。 見直すには `git diff` を使いましょう。 +これによって、今のファイルの状態と、一つ前までのファイルの状態との違いを確かめることができます： + +```bash +$ git diff +``` + +```output +diff --git a/mars.txt b/mars.txt +index df0654a..315bf3a 100644 +--- a/mars.txt ++++ b/mars.txt +@@ -1 +1,2 @@ + Cold and dry, but everything is my favorite color ++The two moons may be a problem for Wolfman +``` + +すると、暗号のようなメッセージが出力されます。 +これらのメッセージは、エディタや `patch` といったプログラムで使われる +一連のコマンドで、ファイルをどうやって再構成するのかが書かれています。 +分かりやすいように、一文ずつ見てみましょう： + +1. 最初の文は、Git が古いバージョンと新しいバージョンのファイルをUnix の`diff`コマンドと同じように、二つのファイルを比べていることを表しています。 +2. 次に、Git が比べているファイルの正確なバージョンを表示しています。`df0654a` と `315bf3a` はコンピュータが作成した、各バージョン"につけられたIDです。 +3. 3・4つ目の文章は、変更されているファイルの名前を表示しています。 +4. 残りの文章が一番重要です。ここに、何が変わり、どの行が変更されたのかが記されています。 + 特に、この`+` マークは、どこに文章が加えられたのかを表しています。 + +変更点を確認したら、コミットしましょう： + +```bash +$ git commit -m "Add concerns about effects of Mars' moons on Wolfman" +``` + +```output +On branch main +Changes not staged for commit: + (use "git add ..." to update what will be committed) + (use "git checkout -- ..." to discard changes in working directory) + + modified: mars.txt + +no changes added to commit (use "git add" and/or "git commit -a") +``` + +おっと、 +初めに `git add` を使わなかったので、 Git はコミットさせてくれませんでした。 +直しましょう： +Let's fix that: + +```bash +$ git add mars.txt +$ git commit -m "Add concerns about effects of Mars' moons on Wolfman" +``` + +```output +[main 34961b1] Add concerns about effects of Mars' moons on Wolfman + 1 file changed, 1 insertion(+) +``` + +Git は変更をコミットする前に、コミットしたいファイルを +追加するように要求してきます。 これによって、変更点をこまめに、そして論理的に分割して保存ができ、大きな変更をひとまとめに保存しなくてもよくなります。 +例えば、論文にいくつか引用源を加えるとします。 +これらの引用源、そして使われた参考文献の目録を、まだ書き終わっていない結論とは_別に_保存したい場合はどうすればいいのでしょう。 + +Git には、まだコミットされていない[changeset](../learners/reference.md#changeset)（一連の変更点）を一時的に保存・把握するために使われる、_staging area_（ステージング・エリア）と呼ばれる特殊な場所が存在します。 + +::::::::::::::::::::::::::::::::::::::::: callout + +## ステージングエリア + +仮にGit を、プロジェクトの一生の間に起こった変更内容を「スナップショット」として保存するものとして考えると、`git add` は_何が_スナップショットに含まれる（ステージングエリアに入れる）のかを指定して、`git commit` は_実際にスナップショットを撮り_、コミットとして永久保存します。 +`git commit` と入力した際にステージングエリアに何もなかった場合、Git は`git commit -a` もしくは `git commit --all` を入力するように言ってきます。このコマンドは、写真を撮る時の「全員集合！」のようなもので、全ての変更点を強制的にコミットできます。 +ですが、大抵は、コミットしたい変更点のみをステージングエリアに入れるほうが良いでしょう。これによって、不要な変更点を間違えてコミットすることもありません。 （集合写真の例に例えると、メイクの不完全なエキストラがステージの上を横断しているのを一緒に撮ってしまった、みたいなものです。） +ですので、ステージングエリアにどの変更点を入れるかは自分で管理しましょう。さもないと、必要以上に「git コミットやり直す」で検索をかけることになるでしょう。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +![](fig/git-staging-area.svg){alt='The Git Staging Area'} + +それでは、ファイルの変更点がエディタからステージングエリア、そして長期保存に移る過程を見てみましょう。 +初めに、新しい文章をファイルに加えましょう： + +```bash +$ nano mars.txt +$ cat mars.txt +``` + +```output +Cold and dry, but everything is my favorite color +The two moons may be a problem for Wolfman +But the Mummy will appreciate the lack of humidity +``` + +```bash +$ git diff +``` + +```output +diff --git a/mars.txt b/mars.txt +index 315bf3a..b36abfd 100644 +--- a/mars.txt ++++ b/mars.txt +@@ -1,2 +1,3 @@ + Cold and dry, but everything is my favorite color + The two moons may be a problem for Wolfman ++But the Mummy will appreciate the lack of humidity +``` + +いい感じです。 +これでファイルの最後に新しく文章を足すことができました。 +（左にある `+` マークで記されています。） +それでは変更点をステージングエリアに入れて +`git diff` がなにを表示するのかを見てみましょう： + +```bash +$ git add mars.txt +$ git diff +``` + +何も表示されませんでした。Git が見た限りでは、保存したい変更点と今ディレクトリ内にあるファイルには、これといった違いは無いということになります。 +ですが、こう入力すると： + +```bash +$ git diff --staged +``` + +```output +diff --git a/mars.txt b/mars.txt +index 315bf3a..b36abfd 100644 +--- a/mars.txt ++++ b/mars.txt +@@ -1,2 +1,3 @@ + Cold and dry, but everything is my favorite color + The two moons may be a problem for Wolfman ++But the Mummy will appreciate the lack of humidity +``` + +以前コミットされた状態のファイルとステージングエリアにある変更点の違いが表示されます。 +変更内容を保存しましょう： + +```bash +$ git commit -m "Discuss concerns about Mars' climate for Mummy" +``` + +```output +[main 005937f] Discuss concerns about Mars' climate for Mummy + 1 file changed, 1 insertion(+) +``` + +状態をチェックしましょう： + +```bash +$ git status +``` + +```output +On branch main +nothing to commit, working tree clean +``` + +そして、今までの変更履歴も見てみましょう： + +```bash +$ git log +``` + +```output +commit 005937fbe2a98fb83f0ade869025dc2636b4dad5 (HEAD -> main) +Author: Vlad Dracula +Date: Thu Aug 22 10:14:07 2013 -0400 + + Discuss concerns about Mars' climate for Mummy + +commit 34961b159c27df3b475cfe4415d94a6d1fcd064d +Author: Vlad Dracula +Date: Thu Aug 22 10:07:21 2013 -0400 + + Add concerns about effects of Mars' moons on Wolfman + +commit f22b25e3233b4645dabd0d81e651fe074bd8e73b +Author: Vlad Dracula +Date: Thu Aug 22 09:51:46 2013 -0400 + + Start notes on Mars as a base +``` + +::::::::::::::::::::::::::::::::::::::::: callout + +## 文字ごとの違いを表示する + +時折、例えばテキストドキュメントなど、列ごとの違いを表示するのは大雑把すぎる場合があります。 こういう時は、`git diff` の `--color-words` オプションを使えば、色で文字ごとの違いを表示してくれるので、大変便利です。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::::: callout + +## ログをめくる + +`git log` の出力がスクリーンよりも長いと、`git` はスクリーンに収まるようにログを分割して表示するプログラムを使います。 +この "pager" （ページャ）というプログラムが開くと、一番下の列がプロンプトではなく、`:` になります。 + +- ページャを閉じるには Q を押してください。 +- 次のページを表示するには Spacebarを押してください。 +- ある `<文字>` を全ページの中から検索する時は、/ を押し、`<文字>` を入力してください。 Nを押すと次の一致場所に行けます。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::::: callout + +## ログの出力を制限する + +`git log` の出力がスクリーン全体を埋めないようにするために、Gitが表示するコミットの数を `-N` で変えることができます。この `N`は、表示したいコミットの数を表しています。 例えば、最新のコミットの情報だけを表示したい場合は、こう入力します： + +```bash +$ git log -1 +``` + +```output +commit 005937fbe2a98fb83f0ade869025dc2636b4dad5 (HEAD -> main) +Author: Vlad Dracula +Date: Thu Aug 22 10:14:07 2013 -0400 + + Discuss concerns about Mars' climate for Mummy +``` + +`--oneline` オプションを使うことによって、表示する情報を制限する事ができます： + +```bash +$ git log --oneline +``` + +```output +005937f (HEAD -> main) Discuss concerns about Mars' climate for Mummy +34961b1 Add concerns about effects of Mars' moons on Wolfman +f22b25e Start notes on Mars as a base +``` + +`--oneline` オプションを他のオプションと組み合わせることもできます。 便利な組み合わせの一つとして、 `--graph` を追加すると、コミット履歴をテキストベースのグラフとして表示し、どのコミットが現在の `HEAD`、現在のブランチ `main`、あるいは[その他の Git リファレンス][git-references]に関連しているかを示すことができます： + +```bash +$ git log --oneline --graph +``` + +```output +* 005937f (HEAD -> main) Discuss concerns about Mars' climate for Mummy +* 34961b1 Add concerns about effects of Mars' moons on Wolfman +* f22b25e Start notes on Mars as a base +``` + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::::: callout + +## ディレクトリ + +Git でディレクトリを使用する際は、以下の二点を覚えておきましょう。 + +1. Git はディレクトリ単体を追跡することはなく、ディレクトリ内のファイルのみを追跡します。 + 自分で試してみてください： + +```bash +$ mkdir spaceships +$ git status +$ git add spaceships +$ git status +``` + +注目してほしいのは、新しく作った `directory` ディレクトリは `git add` でリポジトリに追加したにも関わらず、追跡されてないファイルのリストに表示されていません。 たまに `.gitkeep` ファイルが空のディレクトリ内にあるのは、このためです。 `.gitignore`とは違って、このファイルは特別でも何でもなく、空のディレクトリを Git のリポジトリに追加、そして追跡させるためだけに置いてあるだけです。 なので、別の名前のファイルでも同じことができます。 + +2. Git リポジトリ内でディレクトリを作成し、複数のファイルをそのディレクトリに入れたい場合、ディレクトリ内のファイルをひとまとめに追加する事ができます： + +```bash +git add +``` + +自分で試してみてください： + +```bash +$ touch spaceships/apollo-11 spaceships/sputnik-1 +$ git status +$ git add spaceships +$ git status +``` + +次に進む前に、これらの変更をコミットしましょう。 + +```bash +$ git commit -m "Add some initial thoughts on spaceships" +``` + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +まとめると、変更内容をリポジトリに追加したい時は`git add` で変更点をステージングエリアに移してから、`git commit` でステージングエリアの変更点をリポジトリに保存します： + +![](fig/git-committing.svg){alt='The Git Commit Workflow'} + +::::::::::::::::::::::::::::::::::::::: challenge + +## コミットメッセージを決める + +以下のコミットメッセージの内、最後の `mars.txt` のコミットに最適なメッセージはどれでしょう？ + +1. "Changes" +2. "Added line 'But the Mummy will appreciate the lack of humidity' to mars.txt" +3. "Discuss effects of Mars' climate on the Mummy" + +::::::::::::::: solution + +## 解答 + +１つ目のメッセージは短すぎてコミットの内容が何なのかわかりにくいです。２つ目は`git diff`で何が変わったのかが分かるので、長い割にはあまり意味がありません。３つ目は、短く、簡潔で、分かりやすいメッセージです。 + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## Git に変更点をコミットする + +以下の内、`myfile.txt` を Git リポジトリに保存するためのコマンドはどれでしょう？ + +1. ```bash + ``` + +$ git commit -m "my recent changes" + +```` +2. ```bash +$ git init myfile.txt +$ git commit -m "my recent changes" +```` + +3. ```bash + ``` + +$ git add myfile.txt +$ git commit -m "my recent changes" + +```` +4. ```bash +$ git commit -m myfile.txt "my recent changes" +```` + +::::::::::::::: solution + +## 解答 + +1. ファイルがステージングエリアにない限り、コミットできません。 + +2. 新しくリポジトリを作ろうとします。 + +3. 正しい回答です。まずファイルをステージングエリアに追加し、それからコミットします。 + +4. "my recent changes" というファイルを myfile.txt というメッセージでコミットしようとします。 + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## 複数のファイルをコミットする + +一つのコミットに対し、ステージングエリアは複数のファイルの変更点を保持する事ができます。 + +1. `mars.txt` に、火星ではなく金星に基地を作ることにしたという文章を加えましょう。 +2. 新しく `venus.txt` というファイルを作り、金星に基地を置く決断についての感想を書きましょう。 +3. 二つのファイルの変更内容をステージングエリアに加えて、コミットしましょう。 + +::::::::::::::: solution + +## 解答 + +以下の`cat mars.txt`の出力は、この課題で追加された内容のみを反映しています。 出力は異なる場合があります。 + +まずは `mars.txt` と `venus.txt` を編集しましょう： + +```bash +$ nano mars.txt +$ cat mars.txt +``` + +```output +Maybe I should start with a base on Venus. +``` + +```bash +$ nano venus.txt +$ cat venus.txt +``` + +```output +Venus is a nice planet and I definitely should consider it as a base. +``` + +これで二つのファイルをステージングエリアに追加することができます。 二つのファイルを一気に追加するには： + +```bash +$ git add mars.txt venus.txt +``` + +一つずつ追加するには： + +```bash +$ git add mars.txt +$ git add venus.txt +``` + +これでファイルをコミットする準備ができました。 `git status` でチェックしましょう。 コミットをするには： + +```bash +$ git commit -m "Write plans to start a base on Venus" +``` + +```output +[main cc127c2] + Write plans to start a base on Venus + 2 files changed, 2 insertions(+) + create mode 100644 venus.txt +``` + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## `bio` リポジトリ + +- `bio` という Git リポジトリ新しく作りましょう。 +- `me.txt` というファイルに自分について３文書いて、変更点をコミットしてください。 +- すでに書いた文章の内、ひとつだけ編集して、更にもう一文加えてください。 +- 編集した後の状態とその前の違いを表示してください。 + +::::::::::::::: solution + +## 解答 + +必要であれば、`planets` から出ましょう： + +```bash +$ cd .. +``` + +新しく `bio` というディレクトリを作り、中に移動しましょう： + +```bash +$ mkdir bio +$ cd bio +``` + +リポジトリを作りましょう： + +```bash +$ git init +``` + +`nano` か他のテキストエディタで `me.txt` を作りましょう。 +作ったら、変更点を追加してコミットしてください： + +```bash +$ git add me.txt +$ git commit -m "Add biography file" +``` + +指示通りにファイルを編集してください（一文だけ変えて、もう一文足す）。 +オリジナルと編集後のファイルの違いを表示させるために、`git diff` を使います： + +```bash +$ git diff me.txt +``` + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +[commit-messages]: https://chris.beams.io/posts/git-commit/ + +[git-references]: https://git-scm.com/book/en/v2/Git-Internals-Git-References + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- `git status` はリポジトリの状態を表示する。 +- ファイルはプロジェクトの作業ディレクトリ、ステージング・エリア（次のコミットに含まれる変更点が蓄積される場所）、そしてローカル・リポジトリ（コミットが永久に記録される場所）に保存される。 +- `git add` はファイルをステージング・エリアに移動させる。 +- `git commit` はステージされた内容をローカル・リポジトリに保存する。 +- コミットメッセージは、変更点がわかりやすいように書きましょう。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/05-history.md b/05-history.md new file mode 100644 index 0000000000..bf600f9bbd --- /dev/null +++ b/05-history.md @@ -0,0 +1,554 @@ +--- +title: 履歴の探索 +teaching: 25 +exercises: 0 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- リポジトリのHEADとは何か、またその使い方を説明出来るようになりましょう。 +- Gitのコミット番号を特定して使ってみましょう。 +- 追跡調査されるファイルのいろいろなバージョンを比較してみましょう。 +- ファイルの古いバージョンを復元してみましょう。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- ファイルの古いバージョンを復元するにはどうすればよいでしょうか? +- 変更内容を再調査するにはどうすればよいでしょうか? +- ファイルの古いバージョンを復元するにはどうすればよいでしょうか? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +前のレッスンで見たように、コミットを識別子で参照できます。 識別子 `HEAD` を使うことで作業ディレクトリの _最新のコミット_ を参照できます。 + +`mars.txt` に一度に1行ずつ追加しているので、進展を見て確認することは簡単です。それでは `HEAD` を使ってそれを行ってみましょう。 始める前に、 `mars.txt` にもう1行加えることで変更を加えてみましょう。 + +```bash +$ nano mars.txt +$ cat mars.txt +``` + +```output +Cold and dry, but everything is my favorite color +The two moons may be a problem for Wolfman +But the Mummy will appreciate the lack of humidity +An ill-considered change +``` + +それでは、何が得られるか見てみましょう。 + +```bash +$ git diff HEAD mars.txt +``` + +```output +diff --git a/mars.txt b/mars.txt +index b36abfd..0848c8d 100644 +--- a/mars.txt ++++ b/mars.txt +@@ -1,3 +1,4 @@ + Cold and dry, but everything is my favorite color + The two moons may be a problem for Wolfman + But the Mummy will appreciate the lack of humidity ++An ill-considered change. +``` + +これは、 `HEAD` を省略した場合 (試してみてください) に得られるものと同じです。 これの本当の利点は、以前のコミットを参照できることです。 それを行うには、`HEAD` より前のコミットを参照するために `~1` (「\~」は「チルダ」、発音は [**til**-d_uh_]) を追加します。 + +```bash +$ git diff HEAD~1 mars.txt +``` + +古いコミット間の違いを確認したい場合は、`git diff` を再度使用できますが、`HEAD~1`、`HEAD~2` などの表記を使用して、それらを参照するには下記を行います: + +```bash +$ git diff HEAD~3 mars.txt +``` + +```output +diff --git a/mars.txt b/mars.txt +index df0654a..b36abfd 100644 +--- a/mars.txt ++++ b/mars.txt +@@ -1 +1,4 @@ + Cold and dry, but everything is my favorite color ++The two moons may be a problem for Wolfman ++But the Mummy will appreciate the lack of humidity ++An ill-considered change +``` + +`git diff` を使用して表示されるコミットと作業ディレクトリの _違い_ ではなく、古いコミットで行った変更だけでなくコミットメッセージも表示する `git show`を使用することもできます。 + +```bash +$ git show HEAD~3 mars.txt +``` + +```output +commit f22b25e3233b4645dabd0d81e651fe074bd8e73b +Author: Vlad Dracula +Date: Thu Aug 22 09:51:46 2013 -0400 + + Start notes on Mars as a base + +diff --git a/mars.txt b/mars.txt +new file mode 100644 +index 0000000..df0654a +--- /dev/null ++++ b/mars.txt +@@ -0,0 +1 @@ ++Cold and dry, but everything is my favorite color +``` + +このようにして、コミットのチェーンを構築できます。 +チェーンの最新の終わりは `HEAD` と呼ばれます; `~` 表記を使用して以前のコミットを参照できるため、`HEAD~1` は「以前のコミット」を意味し、`HEAD~123` は現在の場所から123個前のコミットに戻ります。 + +`git log` が表示する、数字と文字の長い文字列を使用してコミットを参照することもできます。 +これらは一個一個の変更に対するユニークなIDであり、「ユニーク」は本当に唯一であることを意味します: どのコンピューターのどのファイルの変更の組み合わせに対しても、ユニークな40文字の ID があります。 +最初のコミットにはID `f22b25e3233b4645dabd0d81e651fe074bd8e73b` が与えられたので、これを試してみましょう: + +```bash +$ git diff f22b25e3233b4645dabd0d81e651fe074bd8e73b mars.txt +``` + +```output +diff --git a/mars.txt b/mars.txt +index df0654a..93a3e13 100644 +--- a/mars.txt ++++ b/mars.txt +@@ -1 +1,4 @@ + Cold and dry, but everything is my favorite color ++The two moons may be a problem for Wolfman ++But the Mummy will appreciate the lack of humidity ++An ill-considered change +``` + +これは正しい答えですが、ランダムな40文字の文字列を入力するのは面倒なので、Gitは最初の数文字だけを使えばよいようにしてくれています: + +```bash +$ git diff f22b25e mars.txt +``` + +```output +diff --git a/mars.txt b/mars.txt +index df0654a..93a3e13 100644 +--- a/mars.txt ++++ b/mars.txt +@@ -1 +1,4 @@ + Cold and dry, but everything is my favorite color ++The two moons may be a problem for Wolfman ++But the Mummy will appreciate the lack of humidity ++An ill-considered change +``` + +やりました! こんなわけで ファイルへの変更を保存して、何が変更されたかを確認できます。 では、どうすれば古いバージョンのものを復元できるでしょうか? +`mars.txt`への最後の更新（「熟考を欠いた変更」）について気が変わったとしましょう。 + +`git status` は、ファイルが変更されたことを示しますが、それらの変更はステージングされていません: + +```bash +$ git status +``` + +```output +On branch main +Changes not staged for commit: + (use "git add ..." to update what will be committed) + (use "git checkout -- ..." to discard changes in working directory) + + modified: mars.txt + +no changes added to commit (use "git add" and/or "git commit -a") +``` + +`git checkout`を使うと、元の状態に戻すことができます: + +```bash +$ git checkout HEAD mars.txt +$ cat mars.txt +``` + +```output +Cold and dry, but everything is my favorite color +The two moons may be a problem for Wolfman +But the Mummy will appreciate the lack of humidity +``` + +その名前から推測できるように、`git checkout` はファイルの古いバージョンをチェックアウト (つまり、復元) します。 +この場合、最後に保存されたコミットである `HEAD` に記録されたファイルのバージョン を復元することをGitに伝えています。 +さらに戻りたい場合は、代わりにコミット Id を使うことができます: + +```bash +$ git checkout f22b25e mars.txt +``` + +```bash +$ cat mars.txt +``` + +```output +Cold and dry, but everything is my favorite color +``` + +```bash +$ git status +``` + +```output +On branch main +Changes to be committed: + (use "git reset HEAD ..." to unstage) + + modified: mars.txt + +``` + +変更はステージング領域にあることに注意してください。 +繰り返しますが、`git checkout` を使うと、元の状態に戻すことができます: + +```bash +$ git checkout HEAD mars.txt +``` + +::::::::::::::::::::::::::::::::::::::::: callout + +## HEAD を見失わないようにしましょう + +上記では下記を使いました + +```bash +$ git checkout f22b25e mars.txt +``` + +`mars.txt` をコミット `f22b25e` 後の状態に戻すためにです。 しかし、気をつけてください！ +コマンド `checkout` には他の重要な機能があり、入力が正確でない場合、Gitはあなたの意図を誤解する可能性があります。 たとえば、前のコマンドで `mars.txt` を忘れた場合です。 + +```bash +$ git checkout f22b25e +``` + +```error +Note: checking out 'f22b25e'. + +You are in 'detached HEAD' state. You can look around, make experimental +changes and commit them, and you can discard any commits you make in this +state without impacting any branches by performing another checkout. + +If you want to create a new branch to retain commits you create, you may +do so (now or later) by using -b with the checkout command again. Example: + + git checkout -b + +HEAD is now at f22b25e Start notes on Mars as a base +``` + +ここでの「HEADが切り離された」状態は「見れるが触ってはいけない」ようなものなので、この状態で変更を加えないでください。 +リポジトリの過去の状態を調査した後、`git checkout main` で `HEAD`を再接続してください。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +取り消したい変更の一個**前**のコミット番号を使う必要があることを覚えておくことが重要です。 +よくある間違いは、破棄しようとしている変更を行ったコミットの番号を使用することです。 +以下の例では、最新のコミットの前 (`HEAD~1`) 、すなわち`f22b25e`から状態を取得したいと考えています: + +![](fig/git-checkout.svg){alt='Git Checkout'} + +つまり、すべてをまとめると、Gitがどのように機能するかは次の漫画のようになります: + +![https://figshare.com/articles/How\_Git\_works\_a\_cartoon/1328266](fig/git_staging.svg) + +::::::::::::::::::::::::::::::::::::::::: callout + +## よくあるケースの簡単化 + +`git status` の出力を注意深く読むと、次のヒントを含んでいることが分かります: + +```output +(use "git checkout -- ..." to discard changes in working directory) +``` + +それが言っているように、バージョン識別子のない `git checkout` はファイルを`HEAD`に保存された状態に復元します。 +二重のダッシュ `--`はコマンドから復元されるファイルの名前を区別するために必要です：それがないと、Git はファイルの名前をコミット Id として使用しようとします。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +ファイルを1つずつ元に戻すことができるという事実は +人々が研究を整理する方法を変えることがあります。 +すべての変更が1つの大きなドキュメントに含まれている場合、 +後で結論に加えられた変更を元に戻さずに、 +序論への変更を元に戻すことは困難です(不可能ではありませんが)。 +一方、序論と結論を別々のファイルに保存すると、時間を前後に移動するのがはるかに簡単になります。 + +::::::::::::::::::::::::::::::::::::::: challenge + +## ファイルの古いバージョンの復元 + +ジェニファーは、数週間取り組んできたPythonスクリプトに変更を加えました。そして今朝行った変更により、スクリプトが "壊れ"、動作しなくなりました。 彼女はそれを修正しようとして約1時間費やしましたが、うまく機能しません... + +幸い、彼女はGitを使用してプロジェクトのバージョンを追跡していました! 以下のどのコマンドで、`data_cruncher.py` と呼ばれるPythonスクリプトの最後にコミットされたバージョンを復元できるでしょうか？ + +1. `$ git checkout HEAD` + +2. `$ git checkout HEAD data_cruncher.py` + +3. `$ git checkout HEAD~1 data_cruncher.py` + +4. `$ git checkout data_cruncher.py` + +5. Both 2 and 4 + +::::::::::::::: solution + +## 解答 + +答えは (5) - 2 と 4 の両方です。 + +The `checkout` command restores files from the repository, overwriting the files in your working +directory. Answers 2 and 4 both restore the _latest_ version _in the repository_ of the file +`data_cruncher.py`. Answer 2 uses `HEAD` to indicate the _latest_, whereas answer 4 uses the +unique ID of the last commit, which is what `HEAD` means. + +Answer 3 gets the version of `data_cruncher.py` from the commit _before_ `HEAD`, which is NOT +what we wanted. + +Answer 1 can be dangerous! Without a filename, `git checkout` will restore **all files** +in the current directory (and all directories below it) to their state at the commit specified. +This command will restore `data_cruncher.py` to the latest commit version, but it will also +restore _any other files that are changed_ to that version, erasing any changes you may +have made to those files! +As discussed above, you are left in a _detached_ `HEAD` state, and you don't want to be there. + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## コミットを戻すことについて + +ジェニファーは同僚とPythonスクリプトで共同作業を行っており、グループのリポジトリへの彼女の最新のコミットが間違っていることに気付き、それを元に戻したいと思っています。 ジェニファーは、グループリポジトリのみんなが正しい変更を取得できるように、正しく元に戻す必要があります。 ジェニファーは、グループリポジトリのみんなが正しい変更を取得できるように、正しく元に戻す必要があります。 `git revert [wrong commit ID]` は、ジェニファーの誤ったコミットを元に戻す新しいコミットを作ります。 + +従って`git revert`は`git checkout [commit ID]`とは異なります。なぜなら `checkout` はグループのリポジトリにはコミットされていないローカルの変更用のコマンドだからです。 + +以下は、ジェニファーが`git revert`を使用するための正しい手順と説明ですが、不足しているコマンドは何でしょうか？ + +1. `________ # コミットIDを見つけるために、プロジェクトのgitの 履歴を見ます` + +2. そのIDをコピーします (IDの最初の数文字は例えば 0b1d055)。 + +3. `git revert [commit ID]` + +4. 新しいコミットメッセージを入力します。 + +5. 保存して閉じます。 + +::::::::::::::: solution + +## 解答 + +The command `git log` lists project history with commit IDs. + +The command `git show HEAD` shows changes made at the latest commit, and lists +the commit ID; however, Jennifer should double-check it is the correct commit, and no one +else has committed changes to the repository. + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## ワークフローと履歴の理解 + +最後のコマンドの出力は何でしょうか？ + +```bash +$ cd planets +$ echo "Venus is beautiful and full of love" > venus.txt +$ git add venus.txt +$ echo "Venus is too hot to be suitable as a base" >> venus.txt +$ git commit -m "Comment on Venus as an unsuitable base" +$ git checkout HEAD venus.txt +$ cat venus.txt #this will print the contents of venus.txt to the screen +``` + +1. ```output + ``` + +Venus is too hot to be suitable as a base + +```` +2. ```output +Venus is beautiful and full of love +```` + +3. ```output + ``` + +Venus is beautiful and full of love +Venus is too hot to be suitable as a base + +```` +4. ```output +Error because you have changed venus.txt without committing the changes +```` + +::::::::::::::: solution + +## 解答 + +答えは2です。 + +The command `git add venus.txt` places the current version of `venus.txt` into the staging area. +The changes to the file from the second `echo` command are only applied to the working copy, +not the version in the staging area. + +So, when `git commit -m "Comment on Venus as an unsuitable base"` is executed, +the version of `venus.txt` committed to the repository is the one from the staging area and +has only one line. + +At this time, the working copy still has the second line (and +`git status` will show that the file is modified). However, `git checkout HEAD venus.txt` +replaces the working copy with the most recently committed version of `venus.txt`. + +So, `cat venus.txt` will output + +```output +Venus is beautiful and full of love. +``` + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## `git diff` の理解のチェック + +このコマンドをよく考えてみてください: `git diff HEAD~9 mars.txt`。 このコマンドを実行したらどうなるだろうと予測しますか? 実行すると何が起こっていますか? またそれはなぜでしょうか? + +別のコマンド `git diff [ID] mars.txt` を試しましょう、ここでの [ID] は最新のコミットのユニークな ID で置き換えられます。 あなたは何が起こるだろうと思いますか? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## ステージされた変更の除去 + +`git checkout` は、ステージされていない変更があったときに 以前のコミットを復元するために使用できます。しかしそれはステージされているがコミットされていない変更に対しても機能するでしょうか? +`mars.txt` に変更を用意し、その変更を加え（`git add`を使い）、`git checkout` を使い変更を取り除くことができるかどうか確かめましょう。 + +::::::::::::::: solution + +## 解答 + +After adding a change, `git checkout` can not be used directly. +Let's look at the output of `git status`: + +```output +On branch main +Changes to be committed: + (use "git reset HEAD ..." to unstage) + + modified: mars.txt + +``` + +Note that if you don't have the same output +you may either have forgotten to change the file, +or you have added it _and_ committed it. + +Using the command `git checkout -- mars.txt` now does not give an error, +but it does not restore the file either. +Git helpfully tells us that we need to use `git reset` first +to unstage the file: + +```bash +$ git reset HEAD mars.txt +``` + +```output +Unstaged changes after reset: +M mars.txt +``` + +Now, `git status` gives us: + +```bash +$ git status +``` + +```output +On branch main +Changes not staged for commit: + (use "git add ..." to update what will be committed) + (use "git checkout -- ..." to discard changes in working directory) + + modified: mars.txt + +no changes added to commit (use "git add" and/or "git commit -a") +``` + +This means we can now use `git checkout` to restore the file +to the previous commit: + +```bash +$ git checkout -- mars.txt +$ git status +``` + +```output +On branch main +nothing to commit, working tree clean +``` + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## 履歴を探索し、要約する + +履歴の探索はgitの重要な要素であり、特にそのコミットが数ヶ月前のものである場合は、適切なコミットIDを見つけるのが難しいことがよくあります。 + +`planets` プロジェクトに50を超えるファイルがあると考えてください。 +あなたは `mars.txt` 中の特定のテキストが変更されたコミットを見つけたいとします。 +`git log` と入力すると、非常に長いリストが表示されました。 +どうやって探す範囲を限定しますか? + +`git diff` コマンドを使用すると、1つの特定のファイルを探索できることを思い出してください、 例えば、`git diff mars.txt` 。 ここでも同様のアイデアを適用できます。 + +```bash +$ git log mars.txt +``` + +Unfortunately some of these commit messages are very ambiguous, e.g., `update files`. +How can you search through these files? + +Both `git diff` and `git log` are very useful and they summarize a different part of the history +for you. +Is it possible to combine both? Let's try the following: + +```bash +$ git log --patch mars.txt +``` + +You should get a long list of output, and you should be able to see both commit messages and +the difference between each commit. + +Question: What does the following command do? + +```bash +$ git log --patch HEAD~9 *.txt +``` + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- `git diff` は、コミット間の違いを表示します。 +- `git checkout` は、ファイルの古いバージョンを復元します。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/06-ignore.md b/06-ignore.md new file mode 100644 index 0000000000..7adfc1d0a5 --- /dev/null +++ b/06-ignore.md @@ -0,0 +1,344 @@ +--- +title: ファイルを無視する +teaching: 5 +exercises: 0 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- Git で追跡したくないファイルを指定しましょう +- ファイルを無視する利点を理解しましょう + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- Git で追跡したくないファイルを指定するにはどうすればよいですか？ + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +Git に追跡して欲しくないファイル、例えばエディタが作成したバックアップファイルやデータ解析中に作られた中間ファイルなどは、どう対処すればいいのでしょう？ +例として、いくつかファイルを作ってみましょう： + +```bash +$ mkdir results +$ touch a.csv b.csv c.csv results/a.out results/b.out +``` + +そして Git が何と言うか見てみましょう： + +```bash +$ git status +``` + +```output +On branch main +Untracked files: + (use "git add ..." to include in what will be committed) + + a.csv + b.csv + c.csv + results/ + +nothing added to commit but untracked files present (use "git add" to track) +``` + +これらのファイルをバージョンコントロールで保存するのはディスク容量の無駄になります。 +さらに、これら全てが表示されると、本当に必要な変更点に集中できなくなってしまうかもしれないので、 +Git にこれらのファイルを無視してもらいましょう。 + +これをするには、`.gitignore` というファイルをルートディレクトリに作ります： + +```bash +$ nano .gitignore +$ cat .gitignore +``` + +```output +*.csv +results/ +``` + +入力したパターンは、 Git に `.dat` で終わるファイル名と`results` ディレクトリ内にあるファイルを無視するように指示しています。 +（Git がすでに追跡しているファイルは、引き続き追跡されます。） + +このファイルを作った後`git status` の出力を見てみると、大分綺麗になっています： + +```bash +$ git status +``` + +```output +On branch main +Untracked files: + (use "git add ..." to include in what will be committed) + + .gitignore + +nothing added to commit but untracked files present (use "git add" to track) +``` + +Git は新しく作られた `.gitignore` ファイルしか表示していません。 +このファイルは追跡しなくても良いかと思うでしょうが、リポジトリを共有する際に、他の人達も私達が無視したものを同じように無視したいでしょう。 +なので、`.gitignore` を追加してコミットしましょう： + +```bash +$ git add .gitignore +$ git commit -m "Ignore data files and the results folder" +$ git status +``` + +```output +On branch main +nothing to commit, working tree clean +``` + +`.gitignore` を作った事によって、間違えて不要なファイルをリポジトリに追加する事を防ぐことができます： + +```bash +$ git add a.csv +``` + +```output +The following paths are ignored by one of your .gitignore files: +a.csv +Use -f if you really want to add them. +``` + +この設定を強制的に無視してファイルを追加するには、`git add -f` を使います。 例えば、`git add -f a.csv` と入力します。 +もちろん、無視されたファイルの状況はいつでも見ることができます： + +```bash +$ git status --ignored +``` + +```output +On branch main +Ignored files: + (use "git add -f ..." to include in what will be committed) + + a.csv + b.csv + c.csv + results/ + +nothing to commit, working tree clean +``` + +::::::::::::::::::::::::::::::::::::::: challenge + +## 埋もれた（ネストされた）ファイルを無視する + +以下のようなディレクトリ構造があるとします： + +```bash +results/data +results/plots +``` + +`results/data` ではなく、`results/plots` のみを無視するにはどうすればいいのでしょう？ + +::::::::::::::: solution + +## 解答 + +`results/plots` 内のファイルのみを無視するのであれば、`.gitignore` に `/plots/` サブフォルダを無視するように.gitignore に以下の文を加えれば解決できます： + +```output +results/plots/ +``` + +この行によって、`results/plots`の内容だけが無視され、`results/data`の内容は無視されません。 + +様々なプログラミングの問題と同様に、この無視ルールが守られるようにする回答方法はいくつかありま。 +The "Ignoring Nested Files: Variation" exercise has a slightly +different directory structure +that presents an alternative solution. +Further, the discussion page has more detail on ignore rules. + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## Including Specific Files + +`final.csv`以外の、ルートディレクトリ内にある他の `.data` ファイルを全て無視したい場合はどうすればいいのでしょう？ +ヒント： `!` （感嘆符）が何をするのか調べてみましょう。 + +::::::::::::::: solution + +## 解答 + +以下二文を .gitignore に加えましょう： + +```output +*.data # 全ての data ファイルを無視する +!final.data # final.data は対象から除外する +``` + +感嘆符は、無視してあったファイルを対象から外します。 + +Note also that because you've previously committed `.csv` files in this +lesson they will not be ignored with this new rule. Only future additions +of `.csv` files added to the root directory will be ignored. + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## Ignoring Nested Files: Variation + +Given a directory structure that looks similar to the earlier Nested Files +exercise, but with a slightly different directory structure: + +```bash +results/data +results/images +results/plots +results/analysis +``` + +How would you ignore all of the contents in the results folder, but not `results/data`? + +Hint: think a bit about how you created an exception with the `!` operator +before. + +::::::::::::::: solution + +## 解答 + +If you want to ignore the contents of +`results/` but not those of `results/data/`, you can change your `.gitignore` to ignore +the contents of results folder, but create an exception for the contents of the +`results/data` subfolder. Your .gitignore would look like this: + +```output +results/* # ignore everything in results folder +!results/data/ # do not ignore results/data/ contents +``` + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## ディレクトリ内の全てのデータファイルを無視する + +空の.gitignoreファイルがあり、以下のようなディレクトリ構造があるとします： + +```bash +results/data/position/gps/a.csv +results/data/position/gps/b.csv +results/data/position/gps/c.csv +results/data/position/gps/info.txt +results/plots +``` + +`result/data/position/gps` 内にある全ての `.data` ファイルを無視する一番短い`.gitignore`ルールは何でしょう？ `info.txt` ファイルは無視しないでください。 + +::::::::::::::: solution + +## 解答 + +`results/data/position/gps/*.data` を使えば `results/data/position/gps` 内にある全ての `.data` ファイルを無視できます。 +`results/data/position/gps/info.txt` ファイルは無視されません。 + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## Ignoring all data Files in the repository + +Let us assume you have many `.csv` files in different subdirectories of your repository. +For example, you might have: + +```bash +results/a.csv +data/experiment_1/b.csv +data/experiment_2/c.csv +data/experiment_2/variation_1/d.csv +``` + +How do you ignore all the `.csv` files, without explicitly listing the names of the corresponding folders? + +::::::::::::::: solution + +## 解答 + +In the `.gitignore` file, write: + +```output +**/*.csv +``` + +This will ignore all the `.csv` files, regardless of their position in the directory tree. +You can still include some specific exception with the exclamation point operator. + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## ルールの順番 + +以下の内容の `.gitignore` ファイルがあるとします： + +```bash +*.csv +!*.csv +``` + +結果的に何が無視されるのでしょうか？ + +::::::::::::::: solution + +## 解答 + +感嘆符 `!` は無視してあったファイルを対象から除外する効果があります。 +`!*.csv` は、その前に入力されている `.csv` ファイルを対象から外すので、全ての `.csv` ファイルは引き続き追跡されることになります。 + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## ログファイル + +仮に `log_01`、 `log_02`、 `log_03`、というように、中間的にログファイルを作成するスクリプトを書いたとします。 +これらのログファイルは取っておきたいのですが、`git` で追跡したくありません。 + +1. `log_01`、 `log_02`、などのファイルを無視するためのルールを**一つだけ** `.gitignore` に入力してください。 + +2. 入力したパターン正常に動作しているか確認するために `log_01` などのファイルを作成してください。 + +3. 最終的に `log_01` ファイルがものすごく重要であることが分かりました。`.gitignore` を編集せずに、このファイルを追跡しているファイルに加えてください。 + +4. 隣の人と、追跡したくないファイルは他にどのようなものがあるのか、そして`.gitignore` に何を入力すればこれらのファイルを無視できるのかを話し合ってください。 + +::::::::::::::: solution + +## 解答 + +1. `log_*` もしくは `log*` を .gitignore に加えます。 + +2. `git add -f log_01` を使って `log_01` を追跡しましょう。 + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- `.gitignore` で無視するファイルを指定する + +:::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/07-github.md b/07-github.md new file mode 100644 index 0000000000..210caf8192 --- /dev/null +++ b/07-github.md @@ -0,0 +1,540 @@ +--- +title: Remotes in GitHub +teaching: 45 +exercises: 0 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- Explain what remote repositories are and why they are useful. +- Push to or pull from a remote repository. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- How do I share my changes with others on the web? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +Version control really comes into its own when we begin to collaborate with +other people. We already have most of the machinery we need to do this; the +only thing missing is to copy changes from one repository to another. + +Systems like Git allow us to move work between any two repositories. In +practice, though, it's easiest to use one copy as a central hub, and to keep it +on the web rather than on someone's laptop. Most programmers use hosting +services like [GitHub](https://github.com), [Bitbucket](https://bitbucket.org) or +[GitLab](https://gitlab.com/) to hold those main copies; we'll explore the pros +and cons of this in a [later episode](13-hosting.md). + +Let's start by sharing the changes we've made to our current project with the +world. To this end we are going to create a _remote_ repository that will be linked to our _local_ repository. + +## 1. Create a remote repository + +Log in to [GitHub](https://github.com), then click on the icon in the top right corner to +create a new repository called `planets`: + +![](fig/github-create-repo-01.png){alt='Creating a Repository on GitHub (Step 1)'} + +Name your repository "planets" and then click "Create Repository". + +Note: Since this repository will be connected to a local repository, it needs to be empty. Leave +"Initialize this repository with a README" unchecked, and keep "None" as options for both "Add +.gitignore" and "Add a license." See the "GitHub License and README files" exercise below for a full +explanation of why the repository needs to be empty. + +![](fig/github-create-repo-02.png){alt='Creating a Repository on GitHub (Step 2)'} + +As soon as the repository is created, GitHub displays a page with a URL and some +information on how to configure your local repository: + +![](fig/github-create-repo-03.png){alt='Creating a Repository on GitHub (Step 3)'} + +This effectively does the following on GitHub's servers: + +```bash +$ mkdir planets +$ cd planets +$ git init +``` + +If you remember back to the earlier [episode](04-changes.md) where we added and +committed our earlier work on `mars.txt`, we had a diagram of the local repository +which looked like this: + +![](fig/git-staging-area.svg){alt='The Local Repository with Git Staging Area'} + +Now that we have two repositories, we need a diagram like this: + +![](fig/git-freshly-made-github-repo.svg){alt='Freshly-Made GitHub Repository'} + +Note that our local repository still contains our earlier work on `mars.txt`, but the +remote repository on GitHub appears empty as it doesn't contain any files yet. + +## 2. Connect local to remote repository + +Now we connect the two repositories. We do this by making the +GitHub repository a [remote](../learners/reference.md#remote) for the local repository. +The home page of the repository on GitHub includes the URL string we need to +identify it: + +![](fig/github-find-repo-string.png){alt='Where to Find Repository URL on GitHub'} + +Click on the 'SSH' link to change the [protocol](../learners/reference.md#protocol) from HTTPS to SSH. + +::::::::::::::::::::::::::::::::::::::::: callout + +## HTTPS vs. SSH + +We use SSH here because, while it requires some additional configuration, it is a +security protocol widely used by many applications. The steps below describe SSH at a +minimum level for GitHub. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +![](fig/github-change-repo-string.png){alt='Changing the Repository URL on GitHub'} + +Copy that URL from the browser, go into the local `planets` repository, and run +this command: + +```bash +$ git remote add origin git@github.com:vlad/planets.git +``` + +Make sure to use the URL for your repository rather than Vlad's: the only +difference should be your username instead of `vlad`. + +`origin` is a local name used to refer to the remote repository. It could be called +anything, but `origin` is a convention that is often used by default in git +and GitHub, so it's helpful to stick with this unless there's a reason not to. + +We can check that the command has worked by running `git remote -v`: + +```bash +$ git remote -v +``` + +```output +origin git@github.com:vlad/planets.git (fetch) +origin git@github.com:vlad/planets.git (push) +``` + +We'll discuss remotes in more detail in the next episode, while +talking about how they might be used for collaboration. + +## 3. SSH Background and Setup + +Before Dracula can connect to a remote repository, he needs to set up a way for his computer to authenticate with GitHub so it knows it's him trying to connect to his remote repository. + +We are going to set up the method that is commonly used by many different services to authenticate access on the command line. This method is called Secure Shell Protocol (SSH). SSH is a cryptographic network protocol that allows secure communication between computers using an otherwise insecure network. + +SSH uses what is called a key pair. This is two keys that work together to validate access. One key is publicly known and called the public key, and the other key called the private key is kept private. Very descriptive names. + +You can think of the public key as a padlock, and only you have the key (the private key) to open it. You use the public key where you want a secure method of communication, such as your GitHub account. You give this padlock, or public key, to GitHub and say "lock the communications to my account with this so that only computers that have my private key can unlock communications and send git commands as my GitHub account." + +What we will do now is the minimum required to set up the SSH keys and add the public key to a GitHub account. + +::::::::::::::::::::::::::::::::::::::::: callout + +## Advanced SSH + +A supplemental episode in this lesson discusses SSH and key pairs in more depth and detail. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +The first thing we are going to do is check if this has already been done on the computer you're on. Because generally speaking, this setup only needs to happen once and then you can forget about it. + +::::::::::::::::::::::::::::::::::::::::: callout + +## Keeping your keys secure + +You shouldn't really forget about your SSH keys, since they keep your account secure. It's good +practice to audit your secure shell keys every so often. Especially if you are using multiple +computers to access your account. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +We will run the list command to check what key pairs already exist on your computer. + +```bash +ls -al ~/.ssh +``` + +Your output is going to look a little different depending on whether or not SSH has ever been set up on the computer you are using. + +Dracula has not set up SSH on his computer, so his output is + +```output +ls: cannot access '/c/Users/Vlad Dracula/.ssh': No such file or directory +``` + +If SSH has been set up on the computer you're using, the public and private key pairs will be listed. The file names are either `id_ed25519`/`id_ed25519.pub` or `id_rsa`/`id_rsa.pub` depending on how the key pairs were set up.\ +Since they don't exist on Dracula's computer, he uses this command to create them. + +### 3.1 Create an SSH key pair + +To create an SSH key pair Vlad uses this command, where the `-t` option specifies which type of algorithm to use and `-C` attaches a comment to the key (here, Vlad's email): + +```bash +$ ssh-keygen -t ed25519 -C "vlad@tran.sylvan.ia" +``` + +If you are using a legacy system that doesn't support the Ed25519 algorithm, use: +`$ ssh-keygen -t rsa -b 4096 -C "your_email@example.com"` + +```output +Generating public/private ed25519 key pair. +Enter file in which to save the key (/c/Users/Vlad Dracula/.ssh/id_ed25519): +``` + +We want to use the default file, so just press Enter. + +```output +Created directory '/c/Users/Vlad Dracula/.ssh'. +Enter passphrase (empty for no passphrase): +``` + +Now, it is prompting Dracula for a passphrase. Since he is using his lab's laptop that other people sometimes have access to, he wants to create a passphrase. Be sure to use something memorable or save your passphrase somewhere, as there is no "reset my password" option. + +```output +Enter same passphrase again: +``` + +After entering the same passphrase a second time, we receive the confirmation + +```output +Your identification has been saved in /c/Users/Vlad Dracula/.ssh/id_ed25519 +Your public key has been saved in /c/Users/Vlad Dracula/.ssh/id_ed25519.pub +The key fingerprint is: +SHA256:SMSPIStNyA00KPxuYu94KpZgRAYjgt9g4BA4kFy3g1o vlad@tran.sylvan.ia +The key's randomart image is: ++--[ED25519 256]--+ +|^B== o. | +|%*=.*.+ | +|+=.E =.+ | +| .=.+.o.. | +|.... . S | +|.+ o | +|+ = | +|.o.o | +|oo+. | ++----[SHA256]-----+ +``` + +The "identification" is actually the private key. You should never share it. The public key is appropriately named. The "key fingerprint" +is a shorter version of a public key. + +Now that we have generated the SSH keys, we will find the SSH files when we check. + +```bash +ls -al ~/.ssh +``` + +```output +drwxr-xr-x 1 Vlad Dracula 197121 0 Jul 16 14:48 ./ +drwxr-xr-x 1 Vlad Dracula 197121 0 Jul 16 14:48 ../ +-rw-r--r-- 1 Vlad Dracula 197121 419 Jul 16 14:48 id_ed25519 +-rw-r--r-- 1 Vlad Dracula 197121 106 Jul 16 14:48 id_ed25519.pub +``` + +### 3.2 Copy the public key to GitHub + +Now we have a SSH key pair and we can run this command to check if GitHub can read our authentication. + +```bash +ssh -T git@github.com +``` + +```output +The authenticity of host 'github.com (192.30.255.112)' can't be established. +RSA key fingerprint is SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8. +This key is not known by any other names +Are you sure you want to continue connecting (yes/no/[fingerprint])? y +Please type 'yes', 'no' or the fingerprint: yes +Warning: Permanently added 'github.com' (RSA) to the list of known hosts. +git@github.com: Permission denied (publickey). +``` + +Right, we forgot that we need to give GitHub our public key! + +First, we need to copy the public key. Be sure to include the `.pub` at the end, otherwise you're looking at the private key. + +```bash +cat ~/.ssh/id_ed25519.pub +``` + +```output +ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDmRA3d51X0uu9wXek559gfn6UFNF69yZjChyBIU2qKI vlad@tran.sylvan.ia +``` + +Now, going to GitHub.com, click on your profile icon in the top right corner to get the drop-down menu. Click "Settings," then on the +settings page, click "SSH and GPG keys," on the left side "Account settings" menu. Click the "New SSH key" button on the right side. Now, +you can add the title (Dracula uses the title "Vlad's Lab Laptop" so he can remember where the original key pair +files are located), paste your SSH key into the field, and click the "Add SSH key" to complete the setup. + +Now that we've set that up, let's check our authentication again from the command line. + +```bash +$ ssh -T git@github.com +``` + +```output +Hi Vlad! You've successfully authenticated, but GitHub does not provide shell access. +``` + +Good! This output confirms that the SSH key works as intended. We are now ready to push our work to the remote repository. + +## 4. Push local changes to a remote + +Now that authentication is setup, we can return to the remote. This command will push the changes from +our local repository to the repository on GitHub: + +```bash +$ git push origin main +``` + +Since Dracula set up a passphrase, it will prompt him for it. If you completed advanced settings for your authentication, it +will not prompt for a passphrase. + +```output +Enumerating objects: 16, done. +Counting objects: 100% (16/16), done. +Delta compression using up to 8 threads. +Compressing objects: 100% (11/11), done. +Writing objects: 100% (16/16), 1.45 KiB | 372.00 KiB/s, done. +Total 16 (delta 2), reused 0 (delta 0) +remote: Resolving deltas: 100% (2/2), done. +To https://github.com/vlad/planets.git + * [new branch] main -> main +``` + +::::::::::::::::::::::::::::::::::::::::: callout + +## Proxy + +If the network you are connected to uses a proxy, there is a chance that your +last command failed with "Could not resolve hostname" as the error message. To +solve this issue, you need to tell Git about the proxy: + +```bash +$ git config --global http.proxy http://user:password@proxy.url +$ git config --global https.proxy https://user:password@proxy.url +``` + +When you connect to another network that doesn't use a proxy, you will need to +tell Git to disable the proxy using: + +```bash +$ git config --global --unset http.proxy +$ git config --global --unset https.proxy +``` + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::::: callout + +## Password Managers + +If your operating system has a password manager configured, `git push` will +try to use it when it needs your username and password. For example, this +is the default behavior for Git Bash on Windows. If you want to type your +username and password at the terminal instead of using a password manager, +type: + +```bash +$ unset SSH_ASKPASS +``` + +in the terminal, before you run `git push`. Despite the name, Git uses +, so +you may want to unset `SSH_ASKPASS` whether you are using Git via SSH or +https. + +You may also want to add `unset SSH_ASKPASS` at the end of your `~/.bashrc` +to make Git default to using the terminal for usernames and passwords. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +Our local and remote repositories are now in this state: + +![](fig/github-repo-after-first-push.svg){alt='GitHub Repository After First Push'} + +::::::::::::::::::::::::::::::::::::::::: callout + +## The '-u' Flag + +You may see a `-u` option used with `git push` in some documentation. This +option is synonymous with the `--set-upstream-to` option for the `git branch` +command, and is used to associate the current branch with a remote branch so +that the `git pull` command can be used without any arguments. To do this, +simply use `git push -u origin main` once the remote has been set up. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +We can pull changes from the remote repository to the local one as well: + +```bash +$ git pull origin main +``` + +```output +From https://github.com/vlad/planets + * branch main -> FETCH_HEAD +Already up-to-date. +``` + +Pulling has no effect in this case because the two repositories are already +synchronized. If someone else had pushed some changes to the repository on +GitHub, though, this command would download them to our local repository. + +::::::::::::::::::::::::::::::::::::::: challenge + +## GitHub GUI + +Browse to your `planets` repository on GitHub. +Underneath the Code button, find and click on the text that says "XX commits" (where "XX" is some number). +Hover over, and click on, the three buttons to the right of each commit. +What information can you gather/explore from these buttons? +How would you get that same information in the shell? + +::::::::::::::: solution + +## Solution + +The left-most button (with the picture of a clipboard) copies the full identifier of the commit +to the clipboard. In the shell, `git log` will show you the full commit identifier for each +commit. + +When you click on the middle button, you'll see all of the changes that were made in that +particular commit. Green shaded lines indicate additions and red ones removals. In the shell we +can do the same thing with `git diff`. In particular, `git diff ID1..ID2` where ID1 and +ID2 are commit identifiers (e.g. `git diff a3bf1e5..041e637`) will show the differences +between those two commits. + +The right-most button lets you view all of the files in the repository at the time of that +commit. To do this in the shell, we'd need to checkout the repository at that particular time. +We can do this with `git checkout ID` where ID is the identifier of the commit we want to +look at. If we do this, we need to remember to put the repository back to the right state +afterwards! + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::::: callout + +## Uploading files directly in GitHub browser + +Github also allows you to skip the command line and upload files directly to +your repository without having to leave the browser. There are two options. +First you can click the "Upload files" button in the toolbar at the top of the +file tree. Or, you can drag and drop files from your desktop onto the file +tree. You can read more about this [on this GitHub page](https://help.github.com/articles/adding-a-file-to-a-repository/). + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## GitHub Timestamp + +Create a remote repository on GitHub. Push the contents of your local +repository to the remote. Make changes to your local repository and push these +changes. Go to the repo you just created on GitHub and check the +[timestamps](../learners/reference.md#timestamp) of the files. How does GitHub +record times, and why? + +::::::::::::::: solution + +## Solution + +GitHub displays timestamps in a human readable relative format (i.e. "22 hours ago" or "three +weeks ago"). However, if you hover over the timestamp, you can see the exact time at which the +last change to the file occurred. + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## Push vs. Commit + +In this episode, we introduced the "git push" command. +How is "git push" different from "git commit"? + +::::::::::::::: solution + +## Solution + +When we push changes, we're interacting with a remote repository to update it with the changes +we've made locally (often this corresponds to sharing the changes we've made with others). +Commit only updates your local repository. + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## GitHub License and README files + +In this episode we learned about creating a remote repository on GitHub, but when you initialized +your GitHub repo, you didn't add a README.md or a license file. If you had, what do you think +would have happened when you tried to link your local and remote repositories? + +::::::::::::::: solution + +## Solution + +In this case, we'd see a merge conflict due to unrelated histories. When GitHub creates a +README.md file, it performs a commit in the remote repository. When you try to pull the remote +repository to your local repository, Git detects that they have histories that do not share a +common origin and refuses to merge. + +```bash +$ git pull origin main +``` + +```output +warning: no common commits +remote: Enumerating objects: 3, done. +remote: Counting objects: 100% (3/3), done. +remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 +Unpacking objects: 100% (3/3), done. +From https://github.com/vlad/planets + * branch main -> FETCH_HEAD + * [new branch] main -> origin/main +fatal: refusing to merge unrelated histories +``` + +You can force git to merge the two repositories with the option `--allow-unrelated-histories`. +Be careful when you use this option and carefully examine the contents of local and remote +repositories before merging. + +```bash +$ git pull --allow-unrelated-histories origin main +``` + +```output +From https://github.com/vlad/planets + * branch main -> FETCH_HEAD +Merge made by the 'recursive' strategy. +README.md | 1 + +1 file changed, 1 insertion(+) +create mode 100644 README.md +``` + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- A local Git repository can be connected to one or more remote repositories. +- Use the SSH protocol to connect to remote repositories. +- `git push` copies changes from a local repository to a remote repository. +- `git pull` copies changes from a remote repository to a local repository. + +:::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/08-collab.md b/08-collab.md new file mode 100644 index 0000000000..441de3d7c2 --- /dev/null +++ b/08-collab.md @@ -0,0 +1,256 @@ +--- +title: Collaborating +teaching: 25 +exercises: 0 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- Clone a remote repository. +- Collaborate by pushing to a common repository. +- Describe the basic collaborative workflow. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- How can I use version control to collaborate with other people? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +For the next step, get into pairs. One person will be the "Owner" and the other +will be the "Collaborator". The goal is that the Collaborator add changes into +the Owner's repository. We will switch roles at the end, so both persons will +play Owner and Collaborator. + +::::::::::::::::::::::::::::::::::::::::: callout + +## Practicing By Yourself + +If you're working through this lesson on your own, you can carry on by opening +a second terminal window. +This window will represent your partner, working on another computer. You +won't need to give anyone access on GitHub, because both 'partners' are you. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +The Owner needs to give the Collaborator access. In your repository page on GitHub, click the "Settings" +button on the right, select "Collaborators", click "Add people", and +then enter your partner's username. + +![](fig/github-add-collaborators.png){alt='screenshot of repository page with Settings then Collaborators selected, showing how to add Collaborators in a GitHub repository'} + +To accept access to the Owner's repo, the Collaborator +needs to go to [https://github.com/notifications](https://github.com/notifications) +or check for email notification. Once there she can accept access to the Owner's repo. + +Next, the Collaborator needs to download a copy of the Owner's repository to her +machine. This is called "cloning a repo". + +The Collaborator doesn't want to overwrite her own version of `planets.git`, so +needs to clone the Owner's repository to a different location than her own +repository with the same name. + +To clone the Owner's repo into her `Desktop` folder, the Collaborator enters: + +```bash +$ git clone git@github.com:vlad/planets.git ~/Desktop/vlad-planets +``` + +Replace 'vlad' with the Owner's username. + +If you choose to clone without the clone path +(`~/Desktop/vlad-planets`) specified at the end, +you will clone inside your own planets folder! +Make sure to navigate to the `Desktop` folder first. + +![](fig/github-collaboration.svg){alt='After Creating Clone of Repository'} + +The Collaborator can now make a change in her clone of the Owner's repository, +exactly the same way as we've been doing before: + +```bash +$ cd ~/Desktop/vlad-planets +$ nano pluto.txt +$ cat pluto.txt +``` + +```output +It is so a planet! +``` + +```bash +$ git add pluto.txt +$ git commit -m "Add notes about Pluto" +``` + +```output + 1 file changed, 1 insertion(+) + create mode 100644 pluto.txt +``` + +Then push the change to the _Owner's repository_ on GitHub: + +```bash +$ git push origin main +``` + +```output +Enumerating objects: 4, done. +Counting objects: 4, done. +Delta compression using up to 4 threads. +Compressing objects: 100% (2/2), done. +Writing objects: 100% (3/3), 306 bytes, done. +Total 3 (delta 0), reused 0 (delta 0) +To https://github.com/vlad/planets.git + 9272da5..29aba7c main -> main +``` + +Note that we didn't have to create a remote called `origin`: Git uses this +name by default when we clone a repository. (This is why `origin` was a +sensible choice earlier when we were setting up remotes by hand.) + +Take a look at the Owner's repository on GitHub again, and you should be +able to see the new commit made by the Collaborator. You may need to refresh +your browser to see the new commit. + +::::::::::::::::::::::::::::::::::::::::: callout + +## Some more about remotes + +In this episode and the previous one, our local repository has had +a single "remote", called `origin`. A remote is a copy of the repository +that is hosted somewhere else, that we can push to and pull from, and +there's no reason that you have to work with only one. For example, +on some large projects you might have your own copy in your own GitHub +account (you'd probably call this `origin`) and also the main "upstream" +project repository (let's call this `upstream` for the sake of examples). +You would pull from `upstream` from time to +time to get the latest updates that other people have committed. + +Remember that the name you give to a remote only exists locally. It's +an alias that you choose - whether `origin`, or `upstream`, or `fred` - +and not something intrinstic to the remote repository. + +The `git remote` family of commands is used to set up and alter the remotes +associated with a repository. Here are some of the most useful ones: + +- `git remote -v` lists all the remotes that are configured (we already used + this in the last episode) +- `git remote add [name] [url]` is used to add a new remote +- `git remote remove [name]` removes a remote. Note that it doesn't affect the + remote repository at all - it just removes the link to it from the local repo. +- `git remote set-url [name] [newurl]` changes the URL that is associated + with the remote. This is useful if it has moved, e.g. to a different GitHub + account, or from GitHub to a different hosting service. Or, if we made a typo when + adding it! +- `git remote rename [oldname] [newname]` changes the local alias by which a remote + is known - its name. For example, one could use this to change `upstream` to `fred`. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +To download the Collaborator's changes from GitHub, the Owner now enters: + +```bash +$ git pull origin main +``` + +```output +remote: Enumerating objects: 4, done. +remote: Counting objects: 100% (4/4), done. +remote: Compressing objects: 100% (2/2), done. +remote: Total 3 (delta 0), reused 3 (delta 0), pack-reused 0 +Unpacking objects: 100% (3/3), done. +From https://github.com/vlad/planets + * branch main -> FETCH_HEAD + 9272da5..29aba7c main -> origin/main +Updating 9272da5..29aba7c +Fast-forward + pluto.txt | 1 + + 1 file changed, 1 insertion(+) + create mode 100644 pluto.txt +``` + +Now the three repositories (Owner's local, Collaborator's local, and Owner's on +GitHub) are back in sync. + +::::::::::::::::::::::::::::::::::::::::: callout + +## A Basic Collaborative Workflow + +In practice, it is good to be sure that you have an updated version of the +repository you are collaborating on, so you should `git pull` before making +our changes. The basic collaborative workflow would be: + +- update your local repo with `git pull origin main`, +- make your changes and stage them with `git add`, +- commit your changes with `git commit -m`, and +- upload the changes to GitHub with `git push origin main` + +It is better to make many commits with smaller changes rather than +of one commit with massive changes: small commits are easier to +read and review. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## Switch Roles and Repeat + +Switch roles and repeat the whole process. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## Review Changes + +The Owner pushed commits to the repository without giving any information +to the Collaborator. How can the Collaborator find out what has changed with +command line? And on GitHub? + +::::::::::::::: solution + +## Solution + +On the command line, the Collaborator can use `git fetch origin main` +to get the remote changes into the local repository, but without merging +them. Then by running `git diff main origin/main` the Collaborator +will see the changes output in the terminal. + +On GitHub, the Collaborator can go to the repository and click on +"commits" to view the most recent commits pushed to the repository. + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## Comment Changes in GitHub + +The Collaborator has some questions about one line change made by the Owner and +has some suggestions to propose. + +With GitHub, it is possible to comment on the diff of a commit. Over the line of +code to comment, a blue comment icon appears to open a comment window. + +The Collaborator posts her comments and suggestions using the GitHub interface. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## Version History, Backup, and Version Control + +Some backup software can keep a history of the versions of your files. They also +allows you to recover specific versions. How is this functionality different from version control? +What are some of the benefits of using version control, Git and GitHub? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- `git clone` copies a remote repository to create a local repository with a remote called `origin` automatically set up. + +:::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/09-conflict.md b/09-conflict.md new file mode 100644 index 0000000000..953b7170ea --- /dev/null +++ b/09-conflict.md @@ -0,0 +1,530 @@ +--- +title: Conflicts +teaching: 15 +exercises: 0 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- Explain what conflicts are and when they can occur. +- Resolve conflicts resulting from a merge. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- What do I do when my changes conflict with someone else's? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +As soon as people can work in parallel, they'll likely step on each other's +toes. This will even happen with a single person: if we are working on +a piece of software on both our laptop and a server in the lab, we could make +different changes to each copy. Version control helps us manage these +[conflicts](../learners/reference.md#conflict) by giving us tools to +[resolve](../learners/reference.md#resolve) overlapping changes. + +To see how we can resolve conflicts, we must first create one. The file +`mars.txt` currently looks like this in both partners' copies of our `planets` +repository: + +```bash +$ cat mars.txt +``` + +```output +Cold and dry, but everything is my favorite color +The two moons may be a problem for Wolfman +But the Mummy will appreciate the lack of humidity +``` + +Let's add a line to the collaborator's copy only: + +```bash +$ nano mars.txt +$ cat mars.txt +``` + +```output +Cold and dry, but everything is my favorite color +The two moons may be a problem for Wolfman +But the Mummy will appreciate the lack of humidity +This line added to Wolfman's copy +``` + +and then push the change to GitHub: + +```bash +$ git add mars.txt +$ git commit -m "Add a line in our home copy" +``` + +```output +[main 5ae9631] Add a line in our home copy + 1 file changed, 1 insertion(+) +``` + +```bash +$ git push origin main +``` + +```output +Enumerating objects: 5, done. +Counting objects: 100% (5/5), done. +Delta compression using up to 8 threads +Compressing objects: 100% (3/3), done. +Writing objects: 100% (3/3), 331 bytes | 331.00 KiB/s, done. +Total 3 (delta 2), reused 0 (delta 0) +remote: Resolving deltas: 100% (2/2), completed with 2 local objects. +To https://github.com/vlad/planets.git + 29aba7c..dabb4c8 main -> main +``` + +Now let's have the owner +make a different change to their copy +_without_ updating from GitHub: + +```bash +$ nano mars.txt +$ cat mars.txt +``` + +```output +Cold and dry, but everything is my favorite color +The two moons may be a problem for Wolfman +But the Mummy will appreciate the lack of humidity +We added a different line in the other copy +``` + +We can commit the change locally: + +```bash +$ git add mars.txt +$ git commit -m "Add a line in my copy" +``` + +```output +[main 07ebc69] Add a line in my copy + 1 file changed, 1 insertion(+) +``` + +but Git won't let us push it to GitHub: + +```bash +$ git push origin main +``` + +```output +To https://github.com/vlad/planets.git + ! [rejected] main -> main (fetch first) +error: failed to push some refs to 'https://github.com/vlad/planets.git' +hint: Updates were rejected because the remote contains work that you do +hint: not have locally. This is usually caused by another repository pushing +hint: to the same ref. You may want to first integrate the remote changes +hint: (e.g., 'git pull ...') before pushing again. +hint: See the 'Note about fast-forwards' in 'git push --help' for details. +``` + +![](fig/conflict.svg){alt='The Conflicting Changes'} + +Git rejects the push because it detects that the remote repository has new updates that have not been +incorporated into the local branch. +What we have to do is pull the changes from GitHub, +[merge](../learners/reference.md#merge) them into the copy we're currently working in, and then push that. +Let's start by pulling: + +```bash +$ git pull origin main +``` + +```output +remote: Enumerating objects: 5, done. +remote: Counting objects: 100% (5/5), done. +remote: Compressing objects: 100% (1/1), done. +remote: Total 3 (delta 2), reused 3 (delta 2), pack-reused 0 +Unpacking objects: 100% (3/3), done. +From https://github.com/vlad/planets + * branch main -> FETCH_HEAD + 29aba7c..dabb4c8 main -> origin/main +Auto-merging mars.txt +CONFLICT (content): Merge conflict in mars.txt +Automatic merge failed; fix conflicts and then commit the result. +``` + +The `git pull` command updates the local repository to include those +changes already included in the remote repository. +After the changes from remote branch have been fetched, Git detects that changes made to the local copy +overlap with those made to the remote repository, and therefore refuses to merge the two versions to +stop us from trampling on our previous work. The conflict is marked in +in the affected file: + +```bash +$ cat mars.txt +``` + +```output +Cold and dry, but everything is my favorite color +The two moons may be a problem for Wolfman +But the Mummy will appreciate the lack of humidity +<<<<<<< HEAD +We added a different line in the other copy +======= +This line added to Wolfman's copy +>>>>>>> dabb4c8c450e8475aee9b14b4383acc99f42af1d +``` + +Our change is preceded by `<<<<<<< HEAD`. +Git has then inserted `=======` as a separator between the conflicting changes +and marked the end of the content downloaded from GitHub with `>>>>>>>`. +(The string of letters and digits after that marker +identifies the commit we've just downloaded.) + +It is now up to us to edit this file to remove these markers +and reconcile the changes. +We can do anything we want: keep the change made in the local repository, keep +the change made in the remote repository, write something new to replace both, +or get rid of the change entirely. +Let's replace both so that the file looks like this: + +```bash +$ cat mars.txt +``` + +```output +Cold and dry, but everything is my favorite color +The two moons may be a problem for Wolfman +But the Mummy will appreciate the lack of humidity +We removed the conflict on this line +``` + +To finish merging, +we add `mars.txt` to the changes being made by the merge +and then commit: + +```bash +$ git add mars.txt +$ git status +``` + +```output +On branch main +All conflicts fixed but you are still merging. + (use "git commit" to conclude merge) + +Changes to be committed: + + modified: mars.txt + +``` + +```bash +$ git commit -m "Merge changes from GitHub" +``` + +```output +[main 2abf2b1] Merge changes from GitHub +``` + +Now we can push our changes to GitHub: + +```bash +$ git push origin main +``` + +```output +Enumerating objects: 10, done. +Counting objects: 100% (10/10), done. +Delta compression using up to 8 threads +Compressing objects: 100% (6/6), done. +Writing objects: 100% (6/6), 645 bytes | 645.00 KiB/s, done. +Total 6 (delta 4), reused 0 (delta 0) +remote: Resolving deltas: 100% (4/4), completed with 2 local objects. +To https://github.com/vlad/planets.git + dabb4c8..2abf2b1 main -> main +``` + +Git keeps track of what we've merged with what, +so we don't have to fix things by hand again +when the collaborator who made the first change pulls again: + +```bash +$ git pull origin main +``` + +```output +remote: Enumerating objects: 10, done. +remote: Counting objects: 100% (10/10), done. +remote: Compressing objects: 100% (2/2), done. +remote: Total 6 (delta 4), reused 6 (delta 4), pack-reused 0 +Unpacking objects: 100% (6/6), done. +From https://github.com/vlad/planets + * branch main -> FETCH_HEAD + dabb4c8..2abf2b1 main -> origin/main +Updating dabb4c8..2abf2b1 +Fast-forward + mars.txt | 2 +- + 1 file changed, 1 insertion(+), 1 deletion(-) +``` + +We get the merged file: + +```bash +$ cat mars.txt +``` + +```output +Cold and dry, but everything is my favorite color +The two moons may be a problem for Wolfman +But the Mummy will appreciate the lack of humidity +We removed the conflict on this line +``` + +We don't need to merge again because Git knows someone has already done that. + +Git's ability to resolve conflicts is very useful, but conflict resolution +costs time and effort, and can introduce errors if conflicts are not resolved +correctly. If you find yourself resolving a lot of conflicts in a project, +consider these technical approaches to reducing them: + +- Pull from upstream more frequently, especially before starting new work +- Use topic branches to segregate work, merging to main when complete +- Make smaller more atomic commits +- Push your work when it is done and encourage your team to do the same to reduce work in progress and, by extension, the chance of having conflicts +- Where logically appropriate, break large files into smaller ones so that it is + less likely that two authors will alter the same file simultaneously + +Conflicts can also be minimized with project management strategies: + +- Clarify who is responsible for what areas with your collaborators +- Discuss what order tasks should be carried out in with your collaborators so + that tasks expected to change the same lines won't be worked on simultaneously +- If the conflicts are stylistic churn (e.g. tabs vs. spaces), establish a + project convention that is governing and use code style tools (e.g. + `htmltidy`, `perltidy`, `rubocop`, etc.) to enforce, if necessary + +::::::::::::::::::::::::::::::::::::::: challenge + +## Solving Conflicts that You Create + +Clone the repository created by your instructor. +Add a new file to it, +and modify an existing file (your instructor will tell you which one). +When asked by your instructor, +pull her changes from the repository to create a conflict, +then resolve it. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## Conflicts on Non-textual files + +What does Git do +when there is a conflict in an image or some other non-textual file +that is stored in version control? + +::::::::::::::: solution + +## Solution + +Let's try it. Suppose Dracula takes a picture of Martian surface and +calls it `mars.jpg`. + +If you do not have an image file of Mars available, you can create +a dummy binary file like this: + +```bash +$ head -c 1024 /dev/urandom > mars.jpg +$ ls -lh mars.jpg +``` + +```output +-rw-r--r-- 1 vlad 57095 1.0K Mar 8 20:24 mars.jpg +``` + +`ls` shows us that this created a 1-kilobyte file. It is full of +random bytes read from the special file, `/dev/urandom`. + +Now, suppose Dracula adds `mars.jpg` to his repository: + +```bash +$ git add mars.jpg +$ git commit -m "Add picture of Martian surface" +``` + +```output +[main 8e4115c] Add picture of Martian surface + 1 file changed, 0 insertions(+), 0 deletions(-) + create mode 100644 mars.jpg +``` + +Suppose that Wolfman has added a similar picture in the meantime. +His is a picture of the Martian sky, but it is _also_ called `mars.jpg`. +When Dracula tries to push, he gets a familiar message: + +```bash +$ git push origin main +``` + +```output +To https://github.com/vlad/planets.git + ! [rejected] main -> main (fetch first) +error: failed to push some refs to 'https://github.com/vlad/planets.git' +hint: Updates were rejected because the remote contains work that you do +hint: not have locally. This is usually caused by another repository pushing +hint: to the same ref. You may want to first integrate the remote changes +hint: (e.g., 'git pull ...') before pushing again. +hint: See the 'Note about fast-forwards' in 'git push --help' for details. +``` + +We've learned that we must pull first and resolve any conflicts: + +```bash +$ git pull origin main +``` + +When there is a conflict on an image or other binary file, git prints +a message like this: + +```output +$ git pull origin main +remote: Counting objects: 3, done. +remote: Compressing objects: 100% (3/3), done. +remote: Total 3 (delta 0), reused 0 (delta 0) +Unpacking objects: 100% (3/3), done. +From https://github.com/vlad/planets.git + * branch main -> FETCH_HEAD + 6a67967..439dc8c main -> origin/main +warning: Cannot merge binary files: mars.jpg (HEAD vs. 439dc8c08869c342438f6dc4a2b615b05b93c76e) +Auto-merging mars.jpg +CONFLICT (add/add): Merge conflict in mars.jpg +Automatic merge failed; fix conflicts and then commit the result. +``` + +The conflict message here is mostly the same as it was for `mars.txt`, but +there is one key additional line: + +```output +warning: Cannot merge binary files: mars.jpg (HEAD vs. 439dc8c08869c342438f6dc4a2b615b05b93c76e) +``` + +Git cannot automatically insert conflict markers into an image as it does +for text files. So, instead of editing the image file, we must check out +the version we want to keep. Then we can add and commit this version. + +On the key line above, Git has conveniently given us commit identifiers +for the two versions of `mars.jpg`. Our version is `HEAD`, and Wolfman's +version is `439dc8c0...`. If we want to use our version, we can use +`git checkout`: + +```bash +$ git checkout HEAD mars.jpg +$ git add mars.jpg +$ git commit -m "Use image of surface instead of sky" +``` + +```output +[main 21032c3] Use image of surface instead of sky +``` + +If instead we want to use Wolfman's version, we can use `git checkout` with +Wolfman's commit identifier, `439dc8c0`: + +```bash +$ git checkout 439dc8c0 mars.jpg +$ git add mars.jpg +$ git commit -m "Use image of sky instead of surface" +``` + +```output +[main da21b34] Use image of sky instead of surface +``` + +We can also keep _both_ images. The catch is that we cannot keep them +under the same name. But, we can check out each version in succession +and _rename_ it, then add the renamed versions. First, check out each +image and rename it: + +```bash +$ git checkout HEAD mars.jpg +$ git mv mars.jpg mars-surface.jpg +$ git checkout 439dc8c0 mars.jpg +$ mv mars.jpg mars-sky.jpg +``` + +Then, remove the old `mars.jpg` and add the two new files: + +```bash +$ git rm mars.jpg +$ git add mars-surface.jpg +$ git add mars-sky.jpg +$ git commit -m "Use two images: surface and sky" +``` + +```output +[main 94ae08c] Use two images: surface and sky + 2 files changed, 0 insertions(+), 0 deletions(-) + create mode 100644 mars-sky.jpg + rename mars.jpg => mars-surface.jpg (100%) +``` + +Now both images of Mars are checked into the repository, and `mars.jpg` +no longer exists. + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## A Typical Work Session + +You sit down at your computer to work on a shared project that is tracked in a +remote Git repository. During your work session, you take the following +actions, but not in this order: + +- _Make changes_ by appending the number `100` to a text file `numbers.txt` +- _Update remote_ repository to match the local repository +- _Celebrate_ your success with some fancy beverage(s) +- _Update local_ repository to match the remote repository +- _Stage changes_ to be committed +- _Commit changes_ to the local repository + +In what order should you perform these actions to minimize the chances of +conflicts? Put the commands above in order in the _action_ column of the table +below. When you have the order right, see if you can write the corresponding +commands in the _command_ column. A few steps are populated to get you +started. + +| order | action . . . . . . . . . . | command . . . . . . . . . . | +| ----- | -------------------------- | --------------------------- | +| 1 | | | +| 2 | | `echo 100 >> numbers.txt` | +| 3 | | | +| 4 | | | +| 5 | | | +| 6 | Celebrate! | `AFK` | + +::::::::::::::: solution + +## Solution + +| order | action . . . . . . | command . . . . . . . . . . . . . . . . . . . | +| ----- | ------------------ | --------------------------------------------- | +| 1 | Update local | `git pull origin main` | +| 2 | Make changes | `echo 100 >> numbers.txt` | +| 3 | Stage changes | `git add numbers.txt` | +| 4 | Commit changes | `git commit -m "Add 100 to numbers.txt"` | +| 5 | Update remote | `git push origin main` | +| 6 | Celebrate! | `AFK` | + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- Conflicts occur when two or more people change the same lines of the same file. +- The version control system does not allow people to overwrite each other's changes blindly, but highlights conflicts so that they can be resolved. + +:::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/10-open.md b/10-open.md new file mode 100644 index 0000000000..23c67d876e --- /dev/null +++ b/10-open.md @@ -0,0 +1,108 @@ +--- +title: オープン サイエンス +teaching: 5 +exercises: 5 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- バージョン管理システムを計算実験用の電子実験ノートとしてどのように活用できるか説明しましょう。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- バージョン管理は、私の研究をよりオープンにするのにどのように役立ちますか? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +> "open" の反対は "closed" ではありません。 +> "open" の反対は "broken" です。 +> +> \--- John Wilbanks + +科学では情報を自由に共有することが理想的かもしれませんが、現実はもっと複雑なことがよくあります。 +最近のよくあるやり方は次のようになります。 + +- 科学者は何らかのデータを収集し、それを自分の部門によって時折バックアップされるマシンに保存します。 +- 次に、科学者はそのデータを分析するために、いくつかの小さなプログラム（これもその科学者のマシンにあります）を作成または変更します。 +- 結果が出たら、それを書き留めて論文を提出します。 + 科学者は自分のデータを含めるかもしれません -- ますます多くのジャーナルがこれを必要としています -- しかし科学者はおそらく自分のコードを含めていません。 +- 時間が経過します。 +- ジャーナルは、科学者の分野の他の少数の人々によって匿名で書かれたレビューを科学者に送信します。 + 科学者はレビューした人を納得させるために自分の論文を改訂し、その間に科学者は以前に書いたスクリプトを修正し、論文を再提出するかもしれません。 +- さらに時間が経過します。 +- ついに論文が出版されます。 + 科学者のデータのオンラインコピーへのリンクが含まれている可能性がありますが、論文自体はペイウォールの背後にあるでしょう：個人的または組織的なアクセス権を持つ人だけがそれを読むことができるでしょう。 + +しかし、ますます多くの科学者にとって、そのプロセスは次のようになります: + +- [figshare](https://figshare.com/)や[Zenodo](https://zenodo.org)などのオープンアクセスリポジトリに保存され、独自の[デジタルオブジェクト識別子](https://ja.wikipedia.org/wiki/%E3%83%87%E3%82%B8%E3%82%BF%E3%83%AB%E3%82%AA%E3%83%96%E3%82%B8%E3%82%A7%E3%82%AF%E3%83%88%E8%AD%98%E5%88%A5%E5%AD%90) (DOI) が与えられます。 + または、データはすでに公開されており、[Dryad](https://datadryad.org/) に保存されています。 +- 科学者は、自分の研究を保持するためにGitHubに新しいリポジトリを作成します。 +- 科学者は分析を行うときに、スクリプト (場合によってはいくつかの出力ファイルも) への変更をそのリポジトリにプッシュします。 + 科学者はまた、自分の論文用にそのリポジトリを使用します；そしてそのリポジトリは、同僚とのコラボレーションのハブになります。 +- 論文の状態に満足したら、[arXiv](https://arxiv.org/)またはその他のプレプリントサーバーに版を投稿し、仲間からのフィードバックを求めます。 +- そのフィードバックに基づいて、科学者は最終的に論文をジャーナルに投稿する前に、いくつかの改訂を投稿する可能性があります。 +- 公開された論文には、科学者のプレプリントとコードそしてデータリポジトリへのリンクが含まれているため、他の科学者が論文の研究を自分の研究の出発点として使用するのがはるかに簡単になります。 + +このオープンモデルは発見を加速します：研究結果がオープンになっていればなっているほど、 +[広く引用され、再利用されます](https://doi.org/10.1371/journal.pone.0000308)。 +ただし、このように作業したい人は、正確に "オープン" が何を意味し、それをどのように行うかについて、いくつかの決定を下す必要があります。 [この本](https://link.springer.com/book/10.1007/978-3-319-00026-8)では、オープンサイエンスのさまざまな側面について詳しく知ることができます。 + +これは、バージョン管理を教える (多くの) 理由の1つです。 +コツコツと使うと、計算作業のための共有可能な電子ラボノートとして機能することによって、 +バージョン管理は "どのように" の質問に答えてくれます： + +- 誰がいつ何をしたかなど、作業の概念的な段階が文書化されています。 すべてのステップには、（ほとんどの場合）固有の識別子 (コミットID) がスタンプされています。 +- 理論的根拠、アイデア、およびその他の知的作業の文書化を、それらから生じる変化に直接結び付けることができます。 +- 独自の回復可能な方法で計算結果を取得するために、研究で使用したものを参照できるようになります。 +- Gitなどのバージョン管理システムを使用すると、リポジトリの履歴全体を簡単にアーカイブして永続化できます。 + +::::::::::::::::::::::::::::::::::::::::: callout + +## コードを引用可能にすること + +バージョン管理リポジトリでホストされているもの（データ、コード、論文など）はすべて、 引用可能なオブジェクトに変換できます。これを行う方法は、 これを行う方法は、[レッスン 12: 引用](12-citation.md)で学習します。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## 私の仕事はどれくらい再現可能ですか？ + +ラボメイトの1人に、あなたの論文やウェブで見つけることができるものだけを使用して、あなたが最近得た結果を再現するように依頼してみましょう。 +ラボメイトの結果の1つに対して同じことを行ってみてから、あなたの研究室由来の結果にそれを行ってみてください。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## 適切なデータリポジトリを見つける方法は? + +数分間インターネットサーフィンして、次のデータリポジトリをチェックしてみましょう：[Figshare](https://figshare.com/), [Zenodo](https://zenodo.org)、[Dryad](https://datadryad.org/)。 研究分野によっては、その分野でよく知られたコミュニティで認められたリポジトリが見つかるかもしれません。 +[Natureが推奨するこれらのデータリポジトリ](https://www.nature.com/sdata/data-policies/repositories)も便利かもしれません。 +現在のプロジェクト用にどのデータリポジトリにアプローチしたいかを隣人と議論し、その理由を説明してみましょう。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## How to Track Large Data or Image Files using Git? + +Large data or image files such as `.md5` or `.psd` file types can be tracked within +a github repository using the [Git Large File Storage](https://git-lfs.github.com) +open source extension tool. This tool automatically uploads large file contents to +a remote server and replaces the file with a text pointer within the github repository. + +Try downloading and installing the Git Large File Storage extension tool, then add +tracking of a large file to your github repository. Ask a colleague to clone your +repository and describe what they see when they access that large file. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- オープンな科学的研究は、クローズドよりも有用であり、引用数が多い。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/11-licensing.md b/11-licensing.md new file mode 100644 index 0000000000..501063361d --- /dev/null +++ b/11-licensing.md @@ -0,0 +1,100 @@ +--- +title: Licensing +teaching: 5 +exercises: 0 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- Explain why adding licensing information to a repository is important. +- Choose a proper license. +- Explain differences in licensing and social expectations. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- What licensing information should I include with my work? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +When a repository with source code, a manuscript or other creative +works becomes public, it should include a file `LICENSE` or +`LICENSE.txt` in the base directory of the repository that clearly +states under which license the content is being made available. This +is because creative works are automatically eligible for intellectual +property (and thus copyright) protection. Reusing creative works +without a license is dangerous, because the copyright holders could +sue you for copyright infringement. + +A license solves this problem by granting rights to others (the +licensees) that they would otherwise not have. What rights are being +granted under which conditions differs, often only slightly, from one +license to another. In practice, a few licenses are by far the most +popular, and [choosealicense.com](https://choosealicense.com/) will +help you find a common license that suits your needs. Important +considerations include: + +- Whether you want to address patent rights. +- Whether you require people distributing derivative works to also + distribute their source code. +- Whether the content you are licensing is source code. +- Whether you want to license the code at all. + +Choosing a license that is in common use makes life easier for +contributors and users, because they are more likely to already be +familiar with the license and don't have to wade through a bunch of +jargon to decide if they're ok with it. The Open Source +Initiative and Free Software +Foundation both +maintain lists of licenses which are good choices. + +[This article][software-licensing] provides an excellent overview of +licensing and licensing options from the perspective of scientists who +also write code. + +At the end of the day what matters is that there is a clear statement +as to what the license is. Also, the license is best chosen from the +get-go, even if for a repository that is not public. Pushing off the +decision only makes it more complicated later, because each time a new +collaborator starts contributing, they, too, hold copyright and will +thus need to be asked for approval once a license is chosen. + +::::::::::::::::::::::::::::::::::::::: challenge + +## Can I Use Open License? + +Find out whether you are allowed to apply an open license to your software. +Can you do this unilaterally, +or do you need permission from someone in your institution? +If so, who? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## What licenses have I already accepted? + +Many of the software tools we use on a daily basis (including in this workshop) are +released as open-source software. Pick a project on GitHub from the list below, or +one of your own choosing. Find its license (usually in a file called `LICENSE` or +`COPYING`) and talk about how it restricts your use of the software. Is it one of +the licenses discussed in this session? How is it different? + +- [Git](https://github.com/git/git), the source-code management tool +- [CPython](https://github.com/python/cpython), the standard implementation of the Python language +- [Jupyter](https://github.com/jupyter), the project behind the web-based Python notebooks we'll be using +- [EtherPad](https://github.com/ether/etherpad-lite), a real-time collaborative editor + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +[software-licensing]: https://doi.org/10.1371/journal.pcbi.1002598 + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- The `LICENSE`, `LICENSE.md`, or `LICENSE.txt` file is often used in a repository to indicate how the contents of the repo may be used by others. +- People who incorporate General Public License (GPL'd) software into their own software must make their software also open under the GPL license; most other open licenses do not require this. +- The Creative Commons family of licenses allow people to mix and match requirements and restrictions on attribution, creation of derivative works, further sharing, and commercialization. +- People who are not lawyers should not try to write licenses from scratch. + +:::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/12-citation.md b/12-citation.md new file mode 100644 index 0000000000..21f9f70b72 --- /dev/null +++ b/12-citation.md @@ -0,0 +1,71 @@ +--- +title: Citation +teaching: 2 +exercises: 0 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- Make your work easy to cite + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- How can I make my work easier to cite? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +You may want to include a file called `CITATION` or `CITATION.txt` +that describes how to reference your project; +the one for Software +Carpentry +states: + +```source +To reference Software Carpentry in publications, please cite both of the following: + +Greg Wilson: "Software Carpentry: Getting Scientists to Write Better +Code by Making Them More Productive". Computing in Science & +Engineering, Nov-Dec 2006. + +Greg Wilson: "Software Carpentry: Lessons Learned". arXiv:1307.5448, +July 2013. + +@article{wilson-software-carpentry-2006, + author = {Greg Wilson}, + title = {Software Carpentry: Getting Scientists to Write Better Code by Making Them More Productive}, + journal = {Computing in Science \& Engineering}, + month = {November--December}, + year = {2006}, +} + +@online{wilson-software-carpentry-2013, + author = {Greg Wilson}, + title = {Software Carpentry: Lessons Learned}, + version = {1}, + date = {2013-07-20}, + eprinttype = {arxiv}, + eprint = {1307.5448} +} +``` + +More detailed advice, and other ways to make your code citable can be found +[at the Software Sustainability Institute blog](https://www.software.ac.uk/how-cite-and-describe-software) and in: + +```source +Smith AM, Katz DS, Niemeyer KE, FORCE11 Software Citation Working Group. (2016) Software citation +principles. [PeerJ Computer Science 2:e86](https://peerj.com/articles/cs-86/) +https://doi.org/10.7717/peerj-cs.8 +``` + +There is also an [`@software{...`](https://www.google.com/search?q=git+citation+%22%40software%7B%22) +[BibTeX](https://www.ctan.org/pkg/bibtex) entry type in case +no "umbrella" citation like a paper or book exists for the project you want to +make citable. + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- Add a CITATION file to a repository to explain how you want your work cited. + +:::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/13-hosting.md b/13-hosting.md new file mode 100644 index 0000000000..7b70d97bd7 --- /dev/null +++ b/13-hosting.md @@ -0,0 +1,106 @@ +--- +title: Hosting +teaching: 10 +exercises: 0 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- Explain different options for hosting scientific work. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- Where should I host my version control repositories? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +The second big question for groups that want to open up their work is where to +host their code and data. One option is for the lab, the department, or the +university to provide a server, manage accounts and backups, and so on. The +main benefit of this is that it clarifies who owns what, which is particularly +important if any of the material is sensitive (i.e., relates to experiments +involving human subjects or may be used in a patent application). The main +drawbacks are the cost of providing the service and its longevity: a scientist +who has spent ten years collecting data would like to be sure that data will +still be available ten years from now, but that's well beyond the lifespan of +most of the grants that fund academic infrastructure. + +Another option is to purchase a domain and pay an Internet service provider +(ISP) to host it. This gives the individual or group more control, and +sidesteps problems that can arise when moving from one institution to another, +but requires more time and effort to set up than either the option above or the +option below. + +The third option is to use a public hosting service like +[GitHub](https://github.com), [GitLab](https://gitlab.com), or +[BitBucket](https://bitbucket.org). +Each of these services provides a web interface that enables people to create, +view, and edit their code repositories. These services also provide +communication and project management tools including issue tracking, wiki pages, +email notifications, and code reviews. These services benefit from economies of +scale and network effects: it's easier to run one large service well than to run +many smaller services to the same standard. It's also easier for people to +collaborate. Using a popular service can help connect your project with +communities already using the same service. + +As an example, Software Carpentry [is on GitHub](https://github.com/swcarpentry/) where you can find the source for this +page. Anyone with a GitHub account can suggest changes to this text. + +GitHub repositories can also be assigned DOIs, by connecting its releases to +Zenodo. For example, +[`10.5281/zenodo.7908089`](https://zenodo.org/record/7908089) is the DOI that has +been "minted" for this introduction to Git. + +Using large, well-established services can also help you quickly take advantage +of powerful tools. One such tool, continuous integration (CI), can +automatically run software builds and tests whenever code is committed or pull +requests are submitted. Direct integration of CI with an online hosting service +means this information is present in any pull request, and helps maintain code +integrity and quality standards. While CI is still available in self-hosted +situations, there is much less setup and maintenance involved with using an +online service. Furthermore, such tools are often provided free of charge to +open source projects, and are also available for private repositories for a fee. + +::::::::::::::::::::::::::::::::::::::::: callout + +## Institutional Barriers + +Sharing is the ideal for science, +but many institutions place restrictions on sharing, +for example to protect potentially patentable intellectual property. +If you encounter such restrictions, +it can be productive to inquire about the underlying motivations and +either to request an exception for a specific project or domain, +or to push more broadly for institutional reform to support more open science. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## Can My Work Be Public? + +Find out whether you are allowed to host your work openly in a public repository. +Can you do this unilaterally, +or do you need permission from someone in your institution? +If so, who? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## Where Can I Share My Work? + +Does your institution have a repository or repositories that you can +use to share your papers, data and software? How do institutional repositories +differ from services like [arXiV](https://arxiv.org/), [figshare](https://figshare.com/), [GitHub](https://github.com/) or [GitLab](https://about.gitlab.com/)? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- Projects can be hosted on university servers, on personal domains, or on a public hosting service. +- Rules regarding intellectual property and storage of sensitive information apply no matter where code and data are hosted. + +:::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/14-supplemental-rstudio.md b/14-supplemental-rstudio.md new file mode 100644 index 0000000000..3c7bbc3b54 --- /dev/null +++ b/14-supplemental-rstudio.md @@ -0,0 +1,185 @@ +--- +title: "Supplemental: Using Git from RStudio" +teaching: 10 +exercises: 0 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- Understand how to use Git from RStudio. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- How can I use Git with RStudio? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +Version control can be very useful when developing data analysis scripts. For +that reason, the popular development environment +[RStudio][rstudio] for the R programming language has built-in +integration with Git. While some advanced Git features still require the +command-line, RStudio has a nice interface for many common Git operations. + +RStudio allows us to create a [project][rstudio-projects] associated with a +given directory to keep track of various related files. To be able to track the +development of the project over time, to be able to revert to previous +versions, and to collaborate with others, we version control the Rstudio +project with Git. To get started using Git in RStudio, we create a new project: + +![](fig/RStudio_screenshot_newproject.png){alt='RStudio screenshot showing the file menu dropdown with "New Project..." selected'} + +This opens a dialog asking us how we want to create the project. We have +some options here. Let's say that we want to use RStudio with the planets +repository that we already made. Since that repository lives in a directory on +our computer, we choose the option "Existing Directory": + +![](fig/RStudio_screenshot_existingdirectory.png){alt='RStudio screenshot showing New Project dialog window with "Create project from existing directory" selected'} + +::::::::::::::::::::::::::::::::::::::::: callout + +## Do You See a "Version Control" Option? + +Although we're not going to use it here, there should be a "version control" +option on this menu. That is what you would click on if you wanted to +create a project on your computer by cloning a repository from GitHub. +If that option is not present, it probably means that RStudio doesn't know +where your Git executable is, and you won't be able to progress further +in this lesson until you tell RStudio where it is. + +### Find your Git Executable + +First let's make sure that Git is installed on your computer. +Open your shell on Mac or Linux, or on Windows open the command prompt +and then type: + +- `which git` (macOS, Linux) +- `where git` (Windows) + +If there is no version of Git on your computer, please follow the +[Git installation instructions](https://swcarpentry.github.io/git-novice/#installing-git) +in the setup of this lesson to install Git now. Next open your shell or command prompt +and type `which git` (macOS, Linux), or `where git` (Windows). +Copy the path to the git executable. + +On one Windows computer which had GitHub Desktop installed on it, the path was: +`C:/Users/UserName/AppData/Local/GitHubDesktop/app-1.1.1/resources/app/git/cmd/git.exe` + +NOTE: The path on your computer will be somewhat different. + +### Tell RStudio where to find GitHub + +In RStudio, go to the `Tools` menu > `Global Options` > `Git/SVN` and then +browse to the Git executable you found in the command prompt or shell. Now restart +RStudio. +Note: Even if you have Git installed, you may need +to accept the Xcode license if you are using macOS. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +Next, RStudio will ask which existing directory we want to use. Click +"Browse..." and navigate to the correct directory, then click "Create Project": + +![](fig/RStudio_screenshot_navigateexisting.png) + +Ta-da! We have created a new project in RStudio within the existing planets +repository. Notice the vertical "Git" menu in the menu bar. RStudio has +recognized that the current directory is a Git repository, and gives us a +number of tools to use Git: + +![](fig/RStudio_screenshot_afterclone.png){alt='RStudio window after new project is created with large arrow pointing to vertical Git menu bar.'} + +To edit the existing files in the repository, we can click on them in the +"Files" panel on the lower right. Now let's add some additional information +about Pluto: + +![](fig/RStudio_screenshot_editfiles.png) + +Once we have saved our edited files, we can use RStudio to commit the changes +by clicking on "Commit..." in the Git menu: + +![](fig/RStudio_screenshot_commit.png){alt='RStudio screenshot showing the Git menu dropdown with "Commit..." selected'} + +This will open a dialogue where we can select which files to commit (by +checking the appropriate boxes in the "Staged" column), and enter a commit +message (in the upper right panel). The icons in the "Status" column indicate +the current status of each file. Clicking on a file shows information about +changes in the lower panel (using output of `git diff`). Once everything is the +way we want it, we click "Commit": + +![](fig/RStudio_screenshot_review.png) + +The changes can be pushed by selecting "Push Branch" from the Git menu. There +are also options to pull from the remote repository, and to view the commit +history: + +![](fig/RStudio_screenshot_history.png){alt='RStudio screenshot showing the git menu dropdown with "History" selected'} + +::::::::::::::::::::::::::::::::::::::::: callout + +## Are the Push/Pull Commands Grayed Out? + +Grayed out Push/Pull commands generally mean that RStudio doesn't know the +location of your remote repository (e.g. on GitHub). To fix this, open a +terminal to the repository and enter the command: `git push -u origin main`. Then restart RStudio. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +If we click on "History", we can see a graphical version of what `git log` +would tell us: + +![](fig/RStudio_screenshot_viewhistory.png) + +RStudio creates a number of files that it uses to keep track of a project. We +often don't want to track these, in which case we add them to our `.gitignore` +file: + +![](fig/RStudio_screenshot_gitignore.png){alt='RStudio screenshot showing .gitignore open in the editor pane with the files .Rproj.user, .Rhistory, .RData, and \*.Rproj added to the end'} + +::::::::::::::::::::::::::::::::::::::::: callout + +## Tip: versioning disposable output + +Generally you do not want to version control disposable output (or read-only +data). You should modify the `.gitignore` file to tell Git to ignore these +files and directories. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## Challenge + +1. Create a new directory within your project called `graphs`. +2. Modify the `.gitignore` so that the `graphs` directory is not version controlled. + +::::::::::::::: solution + +## Solution to Challenge + +This can be done in Rstudio: + +```r +dir.create("./graphs") +``` + +Then open up the `.gitignore` file from the right-hand panel of Rstudio and add +`graphs/` to the list of files to ignore. + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +There are many more features in the RStudio Git menu, but these should be +enough to get you started! + +[rstudio]: https://www.rstudio.com/ + +[rstudio-projects]: https://support.rstudio.com/hc/en-us/articles/200526207-Using-Projects + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- Using RStudio's Git integration allows you to version control a project over time. + +:::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000000..11895988ee --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,13 @@ +--- +title: Contributor Code of Conduct +--- + +As contributors and maintainers of this project, +we pledge to follow the [The Carpentries Code of Conduct][coc]. + +Instances of abusive, harassing, or otherwise unacceptable behavior +may be reported by following our [reporting guidelines][coc-reporting]. + +[coc-reporting]: https://docs.carpentries.org/topic_folders/policies/incident-reporting.html + +[coc]: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000000..b96171fa06 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,83 @@ +--- +title: Licenses +--- + +## Instructional Material + +All Carpentries (Software Carpentry, Data Carpentry, and Library Carpentry) +instructional material is made available under the [Creative Commons +Attribution license][cc-by-human]. The following is a human-readable summary of +(and not a substitute for) the [full legal text of the CC BY 4.0 +license][cc-by-legal]. + +You are free: + +- to **Share**---copy and redistribute the material in any medium or format +- to **Adapt**---remix, transform, and build upon the material + +for any purpose, even commercially. + +The licensor cannot revoke these freedoms as long as you follow the license +terms. + +Under the following terms: + +- **Attribution**---You must give appropriate credit (mentioning that your work + is derived from work that is Copyright (c) The Carpentries and, where + practical, linking to https\://carpentries.org/), provide a [link to the + license][cc-by-human], and indicate if changes were made. You may do so in + any reasonable manner, but not in any way that suggests the licensor endorses + you or your use. + +- **No additional restrictions**---You may not apply legal terms or + technological measures that legally restrict others from doing anything the + license permits. With the understanding that: + +Notices: + +- You do not have to comply with the license for elements of the material in + the public domain or where your use is permitted by an applicable exception + or limitation. +- No warranties are given. The license may not give you all of the permissions + necessary for your intended use. For example, other rights such as publicity, + privacy, or moral rights may limit how you use the material. + +## Software + +Except where otherwise noted, the example programs and other software provided +by The Carpentries are made available under the [OSI][osi]-approved [MIT +license][mit-license]. + +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. + +## Trademark + +"The Carpentries", "Software Carpentry", "Data Carpentry", and "Library +Carpentry" and their respective logos are registered trademarks of [Community +Initiatives][ci]. + +[cc-by-human]: https://creativecommons.org/licenses/by/4.0/ + +[cc-by-legal]: https://creativecommons.org/licenses/by/4.0/legalcode + +[mit-license]: https://opensource.org/licenses/mit-license.html + +[ci]: https://communityin.org/ + +[osi]: https://opensource.org diff --git a/config.yaml b/config.yaml new file mode 100644 index 0000000000..a8b09d6f81 --- /dev/null +++ b/config.yaml @@ -0,0 +1,70 @@ +#------------------------------------------------------------ +#Values for this lesson. +#------------------------------------------------------------ +#Which carpentry is this (swc, dc, lc, or cp)? +#swc: Software Carpentry +#dc: Data Carpentry +#lc: Library Carpentry +#cp: Carpentries (to use for instructor training for instance) +#incubator: The Carpentries Incubator +carpentry: 'swc' +#Overall title for pages. +title: 'Gitによるバージョン管理' +#Date the lesson was created (YYYY-MM-DD, this is empty by default) +created: '2014-12-04' +#Comma-separated list of keywords for the lesson +keywords: 'ソフトウェア, データ, レッスン, カーペントリーズ' +#Life cycle stage of the lesson +#possible values: pre-alpha, alpha, beta, stable +life_cycle: 'stable' +#License of the lesson materials (recommended CC-BY 4.0) +license: 'CC-BY 4.0' +#Link to the source repository for this lesson +source: 'https://github.com/swcarpentry-ja/git-novice' +#Default branch of your lesson +branch: 'main' +#Who to contact if there are any issues +contact: 'team@carpentries.org' +#Navigation ------------------------------------------------ +#Use the following menu items to specify the order of +#individual pages in each dropdown section. Leave blank to +#include all pages in the folder. +#Example ------------- +#episodes: +#- introduction.md +#- first-steps.md +#learners: +#- setup.md +#instructors: +#- instructor-notes.md +#profiles: +#- one-learner.md +#- another-learner.md +#Order of episodes in your lesson +episodes: + - 01-basics.md + - 02-setup.md + - 03-create.md + - 04-changes.md + - 05-history.md + - 06-ignore.md + - 07-github.md + - 08-collab.md + - 09-conflict.md + - 10-open.md + - 11-licensing.md + - 12-citation.md + - 13-hosting.md + - 14-supplemental-rstudio.md +#Information for Learners +learners: +#Information for Instructors +instructors: +#Learner Profiles +profiles: +#Customisation --------------------------------------------- +#This space below is where custom yaml items (e.g. pinning +#sandpaper and varnish versions) should live +url: 'https://swcarpentry.github.io/git-novice' +analytics: carpentries +lang: ja diff --git a/discuss.md b/discuss.md new file mode 100644 index 0000000000..20b94da908 --- /dev/null +++ b/discuss.md @@ -0,0 +1,473 @@ +--- +title: Discussion +--- + +## Frequently Asked Questions + +People often have questions about Git beyond the scope of the core material. +Students who have completed the rest of the lessons might find value in looking through the following topics. + +Note that since this material isn't essential for basic Git usage, it won't be covered by the instructor. + +## More Advanced Git Configuration + +In [Setting Up Git](../episodes/02-setup.md), +we used `git config --global` to set some default options for Git. +It turns out that these configuration options get stored in your home directory +in a plain text file called `.gitconfig`. + +```bash +$ cat ~/.gitconfig +``` + +```output +[user] + name = Vlad Dracula + email = vlad@tran.sylvan.ia +[color] + ui = true +[core] + editor = nano +``` + +This file can be opened in your preferred text editor. +(Note that it is recommended to continue using the `git config` command, +as this helps avoid introducing syntax errors.) + +Eventually, you will want to start customizing Git's behaviour. +This can be done by adding more entries to your `.gitconfig`. +The available options are described in the manual: + +```bash +$ git config --help +``` + +In particular, you might find it useful to add aliases. +These are like shortcuts for longer Git commands. +For example, if you get sick of typing `git checkout` all the time, +you could run the command: + +```bash +$ git config --global alias.co checkout +``` + +Now if we return to the example from [Exploring History](../episodes/05-history.md) where we ran: + +```bash +$ git checkout f22b25e mars.txt +``` + +we could now instead type: + +```bash +$ git co f22b25e mars.txt +``` + +## Styling Git's Log + +A good target for customization is output from the log. +The default log is quite verbose but gives no graphical hints +such as information about which commits were done locally +and which were pulled from remotes. + +You can use `git log --help` and `git config --help` to look for different ways to change +the log output. +Try the following commands and see what effect they have: + +```bash +$ git config --global alias.lg "log --graph" +$ git config --global log.abbrevCommit true +$ git config --global format.pretty oneline +$ git lg +``` + +If you don't like the effects, +you can undo them with: + +```bash +$ git config --global --unset alias.lg +$ git config --global --unset log.abbrevCommit +$ git config --global --unset format.pretty +``` + +::::::::::::::::::::::::::::::::::::::::: callout + +## Undoing Git Configuration Changes + +You can use the `--unset` flag to delete unwanted options from `.gitconfig`. +Another way to roll back changes is to store your `.gitconfig` using Git. + +For hints on what you might want to configure, +go to GitHub and search for "gitconfig". +You will find hundreds of repositories in which people have stored +their own Git configuration files. +Sort them by the number of stars and have a look at the top few. +If you find some you like, +please check that they're covered by an open source license before you clone them. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +## Non-text Files + +Recall when we discussed [Conflicts](../episodes/09-conflict.md) +there was a challenge that asked, +"What does Git do +when there is a conflict in an image or some other non-textual file +that is stored in version control?" + +We will now revisit this in more detail. + +Many people want to version control non-text files, such as images, PDFs and Microsoft Office or LibreOffice documents. +It is true that Git can handle these filetypes (which fall under the banner of "binary" file types). +However, just because it _can_ be done doesn't mean it _should_ be done. + +Much of Git's magic comes from being able to do line-by-line comparisons ("diffs") between files. +This is generally easy for programming source code and marked up text. +For non-text files, a diff can usually only detect that the files have changed +but can't say how or where. + +This has various impacts on Git's performance and will make it difficult to +compare different versions of your project. + +For a basic example to show the difference it makes, +we're going to go see what would have happened if Dracula had tried +using outputs from a word processor instead of plain text. + +Create a new directory and go into it: + +```bash +$ mkdir planets-nontext +$ cd planets-nontext +``` + +Use a program such as Microsoft Word or LibreOffice Writer to create a new document. +Enter the same text that we began with before: + +```output +Cold and dry, but everything is my favorite color +``` + +Save the document into the `planets-nontext` directory with the name of `mars.doc`. +Back in the terminal, run the usual commands for setting up a new Git repository: + +```bash +$ git init +$ git add mars.doc +$ git commit -m "Starting to think about Mars" +``` + +Then make the same changes to `mars.doc` that we (or Vlad) previously made to `mars.txt`. + +```output +Cold and dry, but everything is my favorite color +The two moons may be a problem for Wolfman +``` + +Save and close the word processor. +Now see what Git thinks of your changes: + +```bash +$ git diff +``` + +```output +diff --git a/mars.doc b/mars.doc +index 53a66fd..6e988e9 100644 +Binary files a/mars.doc and b/mars.doc differ +``` + +Compare this to the earlier `git diff` obtained when using text files: + +```output +diff --git a/mars.txt b/mars.txt +index df0654a..315bf3a 100644 +--- a/mars.txt ++++ b/mars.txt +@@ -1 +1,2 @@ + Cold and dry, but everything is my favorite color ++The two moons may be a problem for Wolfman +``` + +Notice how plain text files give a much more informative diff. +You can see exactly which lines changed and what the changes were. + +An uninformative `git diff` is not the only consequence of using Git on binary files. +However, most of the other problems boil down to whether or not a good diff is possible. + +This isn't to say you should _never_ use Git on binary files. +A rule of thumb is that it's OK if the binary file won't change very often, +and if it does change, you don't care about merging in small differences between versions. + +We've already seen how a word processed report will fail this test. +An example that passes the test is a logo for your organization or project. +Even though a logo will be stored in a binary format such as `jpg` or `png`, +you can expect it will remain fairly static through the lifetime of your repository. +On the rare occasion that branding does change, +you will probably just want to replace the logo completely rather than merge little differences in. + +## Removing a File + +Adding and modifying files are not the only actions one might take +when working on a project. It might be required to remove a file +from the repository. + +Create a new file for the planet Nibiru: + +```bash +$ echo "This is another name for fake planet X" > nibiru.txt +``` + +Now add to the repository like you have learned earlier: + +```bash +$ git add nibiru.txt +$ git commit -m 'adding info on nibiru' +$ git status +``` + +```output +On branch main +nothing to commit, working tree clean +``` + +Nibiru is not a real planet. That was a silly idea. Let us remove +it from the disk and let Git know about it: + +```bash +$ git rm nibiru.txt +$ git status +``` + +```output +On branch main +Changes to be committed: + (use "git reset HEAD ..." to unstage) + + deleted: nibiru.txt + +``` + +The change has been staged. Now commit the removal, and remove the +file from the repository itself. Note that the file will be removed +in the new commit. The previous commit will still +have the file, if you were to retrieve that specific commit. + +```bash +$ git commit -m 'Removing info on Nibiru. It is not a real planet!' +``` + +## Removing a File with Unix + +Sometimes we might forget to remove the file through Git. If you removed the +file with Unix `rm` instead of using `git rm`, no worries, +Git is smart enough to notice the missing file. Let us recreate the file and +commit it again. + +```bash +$ echo "This is another name for fake planet X" > nibiru.txt +$ git add nibiru.txt +$ git commit -m 'adding nibiru again' +``` + +Now we remove the file with Unix `rm`: + +```bash +$ rm nibiru.txt +$ git status +``` + +```output +On branch main +Changes not staged for commit: + (use "git add/rm ..." to update what will be committed) + (use "git checkout -- ..." to discard changes in working directory) + + deleted: nibiru.txt + +no changes added to commit (use "git add" and/or "git commit -a") +``` + +See how Git has noticed that the file `nibiru.txt` has been removed +from the disk. The next step is to "stage" the removal of the file +from the repository. This is done with the command `git rm` just as +before. + +```bash +$ git rm nibiru.txt +$ git status +``` + +```output +On branch main +Changes to be committed: + (use "git reset HEAD ..." to unstage) + + deleted: nibiru.txt + +``` + +The change that was made in Unix has now been staged and needs to be +committed. + +```bash +$ git commit -m 'Removing info on Nibiru, again!' +``` + +## Renaming a File + +Another common change when working on a project is to rename a file. + +Create a file for the planet Krypton: + +```bash +$ echo "Superman's home planet" > krypton.txt +``` + +Add it to the repository: + +```bash +$ git add krypton.txt +$ git commit -m 'Adding planet Krypton' +``` + +We all know that Superman moved to Earth. Not that he had much +choice. Now his home planet is Earth. + +Rename the file `krypton.txt` to `earth.txt` with Git: + +```bash +$ git mv krypton.txt earth.txt +$ git status +``` + +```output +On branch main +Changes to be committed: + (use "git reset HEAD ..." to unstage) + + renamed: krypton.txt -> earth.txt +``` + +The final step is commit our change to the repository: + +```bash +$ git commit -m 'Superman's home is now Earth' +``` + +## Renaming a File with Unix + +If you forgot to use Git and you used Unix `mv` instead +of `git mv`, you will have a touch more work to do but Git will +be able to deal with it. Let's try again renaming the file, +this time with Unix `mv`. First, we need to recreate the +`krypton.txt` file: + +```bash +$ echo "Superman's home planet" > krypton.txt +$ git add krypton.txt +$ git commit -m 'Adding planet Krypton again.' +``` + +Let us rename the file and see what Git can figured out by itself: + +```bash +$ mv krypton.txt earth.txt +$ git status +``` + +```output +On branch main +Changes not staged for commit: + (use "git add/rm ..." to update what will be committed) + (use "git checkout -- ..." to discard changes in working directory) + + deleted: krypton.txt + +Untracked files: + (use "git add ..." to include in what will be committed) + + earth.txt + +no changes added to commit (use "git add" and/or "git commit -a") +``` + +Git has noticed that the file `krypton.txt` has disappeared from the +file system and a new file `earth.txt` has showed up. + +Add those changes to the staging area: + +```bash +$ git add krypton.txt earth.txt +$ git status +``` + +```output +On branch main +Changes to be committed: + (use "git reset HEAD ..." to unstage) + + renamed: krypton.txt -> earth.txt + +``` + +Notice how Git has now figured out that the `krypton.txt` has not +disappeared - it has simply been renamed. + +The final step, as before, is to commit our change to the repository: + +```bash +$ git commit -m 'Superman's home is Earth, told you before.' +``` + +## Further .gitignore concepts + +For additional documentation on .gitignore, please reference +[the official git documentation](https://git-scm.com/docs/gitignore). + +In the ignore exercise, learners were presented with two variations of ignoring +nested files. Depending on the organization of your repository, one may suit +your needs over another. Keep in mind that the way that Git travels along +directory paths can be confusing. + +Sometimes the `**` pattern comes in handy, too, which matches multiple +directory levels. E.g. `**/results/plots/*` would make git ignore the +`results/plots` directory in any root directory. + +::::::::::::::::::::::::::::::::::::::: challenge + +## Ignoring Nested Files: Challenge Problem + +Given a directory structure that looks like: + +```bash +results/data +results/plots +results/run001.log +results/run002.log +``` + +And a .gitignore that looks like: + +```output +*.csv +``` + +How would you track all of the contents of `results/data/`, including `*.csv` +files, but ignore the rest of `results/`? + +::::::::::::::: solution + +## Solution + +To do this, your .gitignore would look like this: + +```output +*.csv # ignore the .csv files +results/* # ignore the files in the results directory +!results/data/ # do not ignore the files in results/data +!results/data/* # do not ignore the .csv files in reults/data +``` + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/fig/RStudio_screenshot_afterclone.png b/fig/RStudio_screenshot_afterclone.png new file mode 100644 index 0000000000..268c188c42 Binary files /dev/null and b/fig/RStudio_screenshot_afterclone.png differ diff --git a/fig/RStudio_screenshot_commit.png b/fig/RStudio_screenshot_commit.png new file mode 100644 index 0000000000..66aeeab724 Binary files /dev/null and b/fig/RStudio_screenshot_commit.png differ diff --git a/fig/RStudio_screenshot_editfiles.png b/fig/RStudio_screenshot_editfiles.png new file mode 100644 index 0000000000..251aed4bdf Binary files /dev/null and b/fig/RStudio_screenshot_editfiles.png differ diff --git a/fig/RStudio_screenshot_existingdirectory.png b/fig/RStudio_screenshot_existingdirectory.png new file mode 100644 index 0000000000..27658eee10 Binary files /dev/null and b/fig/RStudio_screenshot_existingdirectory.png differ diff --git a/fig/RStudio_screenshot_gitignore.png b/fig/RStudio_screenshot_gitignore.png new file mode 100644 index 0000000000..225e101784 Binary files /dev/null and b/fig/RStudio_screenshot_gitignore.png differ diff --git a/fig/RStudio_screenshot_history.png b/fig/RStudio_screenshot_history.png new file mode 100644 index 0000000000..52600748e4 Binary files /dev/null and b/fig/RStudio_screenshot_history.png differ diff --git a/fig/RStudio_screenshot_navigateexisting.png b/fig/RStudio_screenshot_navigateexisting.png new file mode 100644 index 0000000000..ef8fcf8c1b Binary files /dev/null and b/fig/RStudio_screenshot_navigateexisting.png differ diff --git a/fig/RStudio_screenshot_newproject.png b/fig/RStudio_screenshot_newproject.png new file mode 100644 index 0000000000..a4f7f79f45 Binary files /dev/null and b/fig/RStudio_screenshot_newproject.png differ diff --git a/fig/RStudio_screenshot_review.png b/fig/RStudio_screenshot_review.png new file mode 100644 index 0000000000..3854b8623a Binary files /dev/null and b/fig/RStudio_screenshot_review.png differ diff --git a/fig/RStudio_screenshot_viewhistory.png b/fig/RStudio_screenshot_viewhistory.png new file mode 100644 index 0000000000..4917409351 Binary files /dev/null and b/fig/RStudio_screenshot_viewhistory.png differ diff --git a/fig/conflict.svg b/fig/conflict.svg new file mode 100644 index 0000000000..ce24496a2c --- /dev/null +++ b/fig/conflict.svg @@ -0,0 +1,309 @@ + + + +image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/fig/git-checkout.svg b/fig/git-checkout.svg new file mode 100644 index 0000000000..fe5599d4f2 --- /dev/null +++ b/fig/git-checkout.svg @@ -0,0 +1,111 @@ + + + + + + + + .git + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + FILE1.txt + + + + + + + + + + + + + + FILE2.txt + + + HEAD + + HEAD~1 + + HEAD~2 + + 892134f + + f22b25e + + 3a54f76 + + + + + + + + + git checkout HEAD~1or git checkout f22b25e + + + repository + + diff --git a/fig/git-committing.svg b/fig/git-committing.svg new file mode 100644 index 0000000000..71b9dcae0c --- /dev/null +++ b/fig/git-committing.svg @@ -0,0 +1,436 @@ + + + +image/svg+xml.git +FILE1.txt +FILE2.txt +git commit +staging area +repository +git add FILE2.txt +git add FILE1.txt + \ No newline at end of file diff --git a/fig/git-freshly-made-github-repo.svg b/fig/git-freshly-made-github-repo.svg new file mode 100644 index 0000000000..2d70ffd175 --- /dev/null +++ b/fig/git-freshly-made-github-repo.svg @@ -0,0 +1,315 @@ + + + +image/svg+xml.git +https://github.com/vlad/planets.git +.git +~/vlad/planets +git add +git commit +staging area +repository + \ No newline at end of file diff --git a/fig/git-staging-area.svg b/fig/git-staging-area.svg new file mode 100644 index 0000000000..c74c2987ee --- /dev/null +++ b/fig/git-staging-area.svg @@ -0,0 +1,93 @@ + + + + + + + + .git + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + git add + + + + + + git commit + + staging area + + repository + + diff --git a/fig/git_staging.svg b/fig/git_staging.svg new file mode 100644 index 0000000000..dd59510bd8 --- /dev/null +++ b/fig/git_staging.svg @@ -0,0 +1,675 @@ + + + +image/svg+xmla2129cb + +892134f + +59e230a + +3a54f76 + +43fe423 + + + + branch + +main + +staging area + +git add file2.txt + +git add file1.txt + +HEADHEAD~1HEAD~2 + +git commit + +git checkout HEAD file1.txt + + + diff --git a/fig/github-add-collaborators.png b/fig/github-add-collaborators.png new file mode 100644 index 0000000000..7833454dfa Binary files /dev/null and b/fig/github-add-collaborators.png differ diff --git a/fig/github-change-repo-string.png b/fig/github-change-repo-string.png new file mode 100644 index 0000000000..7ffe1bfda6 Binary files /dev/null and b/fig/github-change-repo-string.png differ diff --git a/fig/github-collaboration.svg b/fig/github-collaboration.svg new file mode 100644 index 0000000000..2e79e17509 --- /dev/null +++ b/fig/github-collaboration.svg @@ -0,0 +1,767 @@ + + + +image/svg+xml +.gitorigin https://github.com/vlad/planets.git +~/vlad/planets +git add +git commit +staging area +repository +.git +https://github.com/vlad/planets.git +repository +git clone +.gitorigin https://github.com/vlad/planets.git +~/wolfman/planets +git add +git commit +staging area +repository + \ No newline at end of file diff --git a/fig/github-create-repo-01.png b/fig/github-create-repo-01.png new file mode 100644 index 0000000000..6dc6bf2195 Binary files /dev/null and b/fig/github-create-repo-01.png differ diff --git a/fig/github-create-repo-02.png b/fig/github-create-repo-02.png new file mode 100644 index 0000000000..5981881cda Binary files /dev/null and b/fig/github-create-repo-02.png differ diff --git a/fig/github-create-repo-03.png b/fig/github-create-repo-03.png new file mode 100644 index 0000000000..ebce87d5e6 Binary files /dev/null and b/fig/github-create-repo-03.png differ diff --git a/fig/github-find-repo-string.png b/fig/github-find-repo-string.png new file mode 100644 index 0000000000..97d339bd72 Binary files /dev/null and b/fig/github-find-repo-string.png differ diff --git a/fig/github-repo-after-first-push.svg b/fig/github-repo-after-first-push.svg new file mode 100644 index 0000000000..7003395416 --- /dev/null +++ b/fig/github-repo-after-first-push.svg @@ -0,0 +1,483 @@ + + + +image/svg+xml +.gitorigin https://github.com/vlad/planets.git +~/vlad/planets +git add +git commit +staging area +repository +.git +https://github.com/vlad/planets.git +repository +git push origin + \ No newline at end of file diff --git a/fig/merge.svg b/fig/merge.svg new file mode 100644 index 0000000000..bc1378cbab --- /dev/null +++ b/fig/merge.svg @@ -0,0 +1,122 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/fig/motivatingexample.png b/fig/motivatingexample.png new file mode 100644 index 0000000000..e9320a90ee Binary files /dev/null and b/fig/motivatingexample.png differ diff --git a/fig/phd101212s.png b/fig/phd101212s.png new file mode 100644 index 0000000000..c47c428bde Binary files /dev/null and b/fig/phd101212s.png differ diff --git a/fig/play-changes.svg b/fig/play-changes.svg new file mode 100644 index 0000000000..d1a22e79bf --- /dev/null +++ b/fig/play-changes.svg @@ -0,0 +1,175 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/fig/versions.svg b/fig/versions.svg new file mode 100644 index 0000000000..96e8cab171 --- /dev/null +++ b/fig/versions.svg @@ -0,0 +1,247 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/index.md b/index.md new file mode 100644 index 0000000000..36d7e0fc91 --- /dev/null +++ b/index.md @@ -0,0 +1,33 @@ +--- +permalink: index.html +site: sandpaper::sandpaper_site +--- + +ウルフマンとドラキュラはユニバーサル・ミッションズ（ユーフォリック州立大学からスピンオフした宇宙 +サービス）に雇われ、次の惑星着陸船を火星に送ることが可能かどうかを調査しています。 彼らはそれぞれ同時に計画を立てたいのですが、前にもこのような仕事をしようとしたら困ったことがありました。 交代制にすれば、各自がもう片方が終わるのを待つのに多くの時間を費やすことになります。しかし、それぞれ自分のコピーを編集して、メールで添付ファイルを送ったりすると情報の喪失や上書き、複製などといった問題が起こります。 + +同僚が[バーション管理](learners/reference.md#version-control)を使って作業を管理することを勧めました。 バージョン管理はファイルを送り返すよりも優れています： + +- 本当に消そうとしない限り、バージョン管理に入れらた（「コミットされた」）ものが失われることはありません。 古いバージョンのファイルはすべて保存されているため、特定の日に誰が何を書き込んだのか、特定の結果を生成するためにどのバージョンのプログラムが使用されたのかなど、正確に確認することが可能です。 + +- 誰が何をいつ変更したのかという記録があるため、後に問題が生じた場合、連絡するべき人が分かる上に必要に応じて「元に戻す」機能のように、以前のバージョンに戻すことができます。 + +- 同じプロジェクトで複数の人が協力し合う場合、間違って誰かの変更を見落としたり上書きしたりする可能性があります。 バージョン管理システムは、二つの変更点の間に不一致があった場合、自動的にユーザーに知らせてくれます。 + +バージョン管理を使うことによって得をするのはチームだけではありません: 個人で作業をしている研究者にもメリットがあります。 何が、いつ、何故変わったのかを記録しておくことは、後で昔のプロジェクトを見返すことになった場合などに（例えば、1年後、プロジェクトの詳細を忘れてしまった時などに）、非常に便利です。 + +バージョン管理は、デジタル世界における実験ノートです。 +専門家が、自分が行ったことを記録し、 +他の人々と共同作業を行うために使用するものです。 大規模なソフトウェア開発 +プロジェクトはすべてGit に依存しており、ほとんどのプログラマーは小さな仕事 +でも使用しています。 書籍、論文、小規模なデータセット、時間の経過とともに変化するもの、 +共有する必要があるものは、バージョン管理システムに保存することができるし、そう**すべき**です。 + +:::::::::::::::::::::::::::::::::::::::::: prereq + +## 予備知識 + +このレッスンでは、UnixシェルからGitを使います。 +シェルの使用経験があることが望ましいですが、_必須ではありません_。 + +:::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/instructor-notes.md b/instructor-notes.md new file mode 100644 index 0000000000..4d17d74aed --- /dev/null +++ b/instructor-notes.md @@ -0,0 +1,327 @@ +--- +title: Instructor Notes +--- + +Using a software tool to handle the versions of your project files +lets you focus on the more interesting/innovative aspects of your project. + +- Version control's advantages + - It's easy to set up + - Every copy of a Git repository is a full backup of a project and its history + - A few easy-to-remember commands are all you need for most day-to-day version control tasks + - The [GitHub][github] hosting service provides a web-based collaboration service +- Two main concepts + - _commit_: a recorded set of changes in your project's files + - _repository_: the history of all your project's commits +- Why use GitHub? + - No need for a server: easy to set up + - GitHub's strong community: your colleagues are probably already there + +## Overall + +Version control might be the most important topic we teach, but Git is +definitely the most complicated tool. However, GitHub presently dominates the +open software repository landscape, so the time and effort required to teach +fundamental Git is justified and worthwhile. + +Because of this complexity, we don't teach novice learners about many +interesting topics, such as branching, hashes, and commit objects. + +Instead we try to convince them that version control is useful for researchers +working in teams or not, because it is + +- a better way to "undo" changes, +- a better way to collaborate than mailing files back and forth, and +- a better way to share your code and other scientific work with the world. + +## Teaching Notes + +- You can "split" your shell so that recent commands remain in view using [this](https://github.com/rgaiacs/swc-shell-split-window) script. + +- Make sure the network is working _before_ starting this lesson. + +- Drawings are particularly useful in this lesson: if you have a whiteboard, + [use it][drawings]! + +- Version control is usually not the first subject in a workshop, + so get learners to create a GitHub account after the session before. + Remind learners that the username and email they use for GitHub (and setup + during Git configuration) will be viewable to the public by default. + However, there are many reasons why a learner may not want their personal + information viewable, and GitHub has [resources for keeping an email address + private][github-privacy]. + +- If some learners are using Windows, there will inevitably be issues + merging files with different line endings. (Even if everyone's on + some flavor of Unix, different editors may or may not add a + newline to the last line of a file.) Take a moment to explain + these issues, since learners will almost certainly trip over them + again. If learners are running into line ending problems, GitHub + has a [page][github-line-endings] that helps with troubleshooting. + Specifically, the [section on refreshing a repository][github-line-endings-refresh] + may be helpful if learners need to change the `core.autocrlf` setting + after already having made one or more commits. + +- We don't use a Git GUI in these notes because we haven't found one that + installs easily and runs reliably on the three major operating systems, and + because we want learners to understand what commands are being run. That + said, instructors should demo a GUI on their desktop at some point during + this lesson and point learners at [this page][github-gui]. + +- Instructors should show learners graphical diff/merge tools like + [DiffMerge][diffmerge]. + +- When appropriate, explain that we teach Git rather than CVS, Subversion, or + Mercurial primarily because of GitHub's growing popularity: CVS and + Subversion are now seen as legacy systems, and Mercurial isn't nearly as + widely used in the sciences right now. + +- Further resources: + + - [git-it] is a self-paced command-line Git demo, + with [git-it-electron] its GitHub Desktop successor. + - [Code School][code-school] has a free interactive course, [Try Git][try-git]. + - for instructors, [the Git parable][git-parable] is useful background reading + +## [Automated Version Control](../episodes/01-basics.md) + +- Ask, "Who uses 'undo' in their editor?" All say "Me". 'Undo' is the simplest + form of version control. + +- Give learners a five-minute overview of what version control does for them + before diving into the watch-and-do practicals. Most of them will have + tried to co-author papers by emailing files back and forth, or will have + biked into the office only to realize that the USB key with last night's + work is still on the kitchen table. Instructors can also make jokes about + directories with names like "final version", "final version revised", + "final version with reviewer three's corrections", "really final version", + and, "come on this really has to be the last version" to motivate version + control as a better way to collaborate and as a better way to back work up. + +## [Setting Up Git](../episodes/02-setup.md) + +- We suggest instructors and students use `nano` as the text editor for this + lessons because + + - it runs in all three major operating systems, + - it runs inside the shell (switching windows can be confusing to students), and + - it has shortcut help at the bottom of the window. + + Please point out to students during setup that they can and should use + another text editor if they're already familiar with it. + +- When setting up Git, be very clear what learners have to enter: it is + common for them to edit the instructor's details (e.g. email). Check at + the end using `git config --list`. + +- When setting up the default branch name, if learners have a Git version + older than 2.28, the default branch name can be changed for the lesson + using `git branch -M main` if there are currently commits in the repository, + or `git checkout -b main` if there are no commits/the repository is completely empty. + +## [Creating a Repository](../episodes/03-create.md) + +- When you do `git status`, Mac users may see a `.DS_Store` file showing as + untracked. This a file that Mac OS creates in each directory. + +- The challenge "Places to create repositories" tries to reinforce the idea + that the `.git` folder contains the whole Git repo and deleting this folder + undoes a `git init`. It also gives the learner the way to fix the common + mistake of putting unwanted folders (like `Desktop`) under version control. + + Instead of removing the `.git` folder directly, you can choose to move it + first to a safer directory and remove it from there: + + ```bash + $ mv .git temp_git + $ rm -rf temp_git + ``` + + The challenge suggests that it is a bad idea to create a Git repo inside another repo. + For more discussion on this topic, please see [this issue][repos-in-repos]. + +## [Tracking Changes](../episodes/04-changes.md) + +- It's important that learners do a full commit cycle by themselves (make + changes, `git diff`, `git add`, and `git commit`). The "`bio` repository" + challenge does that. + +- This is a good moment to show a diff with a graphical diff tool. If you + skip it because you're short on time, show it once in GitHub. + +- One thing may cause confusion is recovering old versions. If, instead of + doing `$ git checkout f22b25e mars.txt`, someone does `$ git checkout f22b25e`, they wind up in the "detached HEAD" state and confusion abounds. + It's then possible to keep on committing, but things like `git push origin main` a bit later will not give easily comprehensible results. It also + makes it look like commits can be lost. To "re-attach" HEAD, use + `git checkout main`. + +- This is a good moment to show a log within a Git GUI. If you skip it + because you're short on time, show it once in GitHub. + +## [Ignoring Things](../episodes/06-ignore.md) + +Just remember that you can use wildcards and regular expressions to ignore a +particular set of files in `.gitignore`. + +## [Remotes in GitHub](../episodes/07-github.md) + +- Make it clear that Git and GitHub are not the same thing: Git is an open + source version control tool, GitHub is a company that hosts Git + repositories in the web and provides a web interface to interact with repos + they host. + +- It is very useful to draw a diagram showing the different repositories + involved. + +- When pushing to a remote, the output from Git can vary slightly depending on + what leaners execute. The lesson displays the output from git if a learner + executes `git push origin main`. However, some learners might use syntax + suggested by GitHub for pushing to a remote with an existing repository, + which is `git push -u origin main`. Learners using syntax from GitHub, + `git push -u origin main`, will have slightly different output, including + the line `Branch main set up to track remote branch main from origin by rebasing.` + +## [Collaborating](../episodes/08-collab.md) + +- Decide in advance whether all the learners will work in one shared + repository, or whether they will work in pairs (or other small groups) in + separate repositories. The former is easier to set up; the latter runs + more smoothly. + +- Role playing between two instructors can be effective when teaching the + collaboration and conflict sections of the lesson. One instructor can play + the role of the repository owner, while the second instructor can play the + role of the collaborator. If it is possible, try to use two projectors so + that the computer screens of both instructors can be seen. This makes for + a very clear illustration to the students as to who does what. + +- It is also effective to pair up students during this lesson and assign one + member of the pair to take the role of the owner and the other the role of + the collaborator. In this setup, challenges can include asking the + collaborator to make a change, commit it, and push the change to the remote + repository so that the owner can then retrieve it, and vice-versa. The + role playing between the instructors can get a bit "dramatic" in the + conflicts part of the lesson if the instructors want to inject some humor + into the room. + +- If you don't have two projectors, have two instructors at the front of the + room. Each instructor does their piece of the collaboration demonstration + on their own computer and then passes the projector cord back and forth + with the other instructor when it's time for them to do the other part of + the collaborative workflow. It takes less than 10 seconds for each + switchover, so it doesn't interrupt the flow of the lesson. + And of course it helps to give each of the instructors a different-colored + hat, or put different-colored sticky notes on their foreheads. + +- If you're the only instructor, the best way to create is clone the two + repos in your Desktop, but under different names, e.g., pretend one is your + computer at work: + + ```bash + $ git clone https://github.com/vlad/planets.git planets-at-work + ``` + +- It's very common that learners mistype the remote alias or the remote URL + when adding a remote, so they cannot `push`. You can diagnose this with + `git remote -v` and checking carefully for typos. + + - To fix a wrong alias, you can do `git remote rename `. + - To fix a wrong URL, you can do `git remote set-url `. + +- Before cloning the repo, be sure that nobody is inside another repo. The + best way to achieve this is moving to the `Desktop` before cloning: `cd && cd Desktop`. + +- If both repos are in the `Desktop`, have them to clone their collaborator + repo under a given directory using a second argument: + + ```bash + $ git clone https://github.com/vlad/planets.git vlad-planet + ``` + +- The most common mistake is that learners `push` before `pull`ing. If they + `pull` afterward, they may get a conflict. + +- Conflicts, sometimes weird, will start to arise. Stay tight: conflicts are + next. + +- Learners may have slightly different output from `git push` and `git pull` + depending on the version of git, and if upstream (`-u`) is used. + +## [Conflicts](../episodes/09-conflict.md) + +- Expect the learners to make mistakes. Expect _yourself_ to make mistakes. + This happens because it is late in the lesson and everyone is tired. + +- If you're the only instructor, the best way to create a conflict is: + + - Clone your repo in a different directory, pretending is your computer at + work: `git clone https://github.com/vlad/planets.git planets-at-work`. + - At the office, you make a change, commit and push. + - At your laptop repo, you (forget to pull and) make a change, commit and + try to push. + - `git pull` now and show the conflict. + +- Learners usually forget to `git add` the file after fixing the conflict and + just (try to) commit. You can diagnose this with `git status`. + +- Remember that you can discard one of the two parents of the merge: + + - discard the remote file, `git checkout --ours conflicted_file.txt` + - discard the local file, `git checkout --theirs conflicted_file.txt` + + You still have to `git add` and `git commit` after this. This is + particularly useful when working with binary files. + +- Keep in mind that depending on the Git version used, the outputs for + `git push` and `git pull` can vary slightly. + +## [Open Science](../episodes/10-open.md) + +## [Licensing](../episodes/11-licensing.md) + +We teach about licensing because questions about who owns what, or can use +what, arise naturally once we start talking about using public services like +GitHub to store files. Also, the discussion gives learners a chance to catch +their breath after what is often a frustrating couple of hours. + +The Creative Commons family of licenses is recommended for many types of +works (including software documentation and images used in software) but not +software itself. Creative Commons [recommends][cc-faq-software] a +software-specific license instead. + +## [Citation](../episodes/12-citation.md) + +## [Hosting](../episodes/13-hosting.md) + +A common concern for learners is having their work publicly available on +GitHub. While we encourage open science, sometimes private repos are the +only choice. It's always interesting to mention the options to have +web-hosted private repositories. + +[github]: https://github.com/ + +[drawings]: https://marklodato.github.io/visual-git-guide/index-en.html + +[github-privacy]: https://help.github.com/articles/keeping-your-email-address-private/ + +[github-line-endings]: https://docs.github.com/en/github/using-git/configuring-git-to-handle-line-endings + +[github-line-endings-refresh]: https://docs.github.com/en/github/using-git/configuring-git-to-handle-line-endings#refreshing-a-repository-after-changing-line-endings + +[github-gui]: https://git-scm.com/downloads/guis + +[diffmerge]: https://sourcegear.com/diffmerge/ + +[git-it]: https://github.com/jlord/git-it + +[git-it-electron]: https://github.com/jlord/git-it-electron + +[code-school]: https://www.codeschool.com/ + +[try-git]: https://try.github.io + +[git-parable]: https://tom.preston-werner.com/2009/05/19/the-git-parable.html + +[repos-in-repos]: https://github.com/swcarpentry/git-novice/issues/272 + +[cc-faq-software]: https://creativecommons.org/faq/#can-i-apply-a-creative-commons-license-to-software diff --git a/learner-profiles.md b/learner-profiles.md new file mode 100644 index 0000000000..75b2c5cadc --- /dev/null +++ b/learner-profiles.md @@ -0,0 +1,5 @@ +--- +title: FIXME +--- + +This is a placeholder file. Please add content here. diff --git a/md5sum.txt b/md5sum.txt new file mode 100644 index 0000000000..4ab7413cf5 --- /dev/null +++ b/md5sum.txt @@ -0,0 +1,25 @@ +"file" "checksum" "built" "date" +"CODE_OF_CONDUCT.md" "aa54988020ee279c8375831ccd9c229f" "site/built/CODE_OF_CONDUCT.md" "2024-01-13" +"LICENSE.md" "a28efe88838e3073f3f6db11bc125754" "site/built/LICENSE.md" "2024-01-13" +"config.yaml" "b6d9ed3e5970de3643d8c1edf24aae9a" "site/built/config.yaml" "2024-01-13" +"index.md" "5fba22f4ccdf526028f9782ee580cd59" "site/built/index.md" "2024-01-13" +"episodes/01-basics.md" "ba8ce76f1cf8f30c8ceb1a90f89da70e" "site/built/01-basics.md" "2024-01-13" +"episodes/02-setup.md" "4d7bccfd1c241430c9b8e608a6374cdf" "site/built/02-setup.md" "2024-01-13" +"episodes/03-create.md" "09681c18482b4646736c2dd4ea66f24f" "site/built/03-create.md" "2024-01-13" +"episodes/04-changes.md" "1cc85f9469dda0136ead536519420445" "site/built/04-changes.md" "2024-01-13" +"episodes/05-history.md" "3d444b023a9c9baaad5b084fc41b54b1" "site/built/05-history.md" "2024-01-13" +"episodes/06-ignore.md" "d1d5ad3b6c1df1ee13f1ae8aab1d17e4" "site/built/06-ignore.md" "2024-01-13" +"episodes/07-github.md" "f3e457920f932faffd8aecd66f78c24f" "site/built/07-github.md" "2023-11-21" +"episodes/08-collab.md" "99ab7144c3631bb5952a83115e7fae85" "site/built/08-collab.md" "2023-11-21" +"episodes/09-conflict.md" "c94cdba9552057b189a625c98ea23dde" "site/built/09-conflict.md" "2023-11-21" +"episodes/10-open.md" "82c019e04706ed92bf0586d09aa274dc" "site/built/10-open.md" "2024-01-13" +"episodes/11-licensing.md" "f1ae69063f4103a7a32456e9757d9075" "site/built/11-licensing.md" "2023-11-21" +"episodes/12-citation.md" "798f2ada566d42e901b37d3129e47518" "site/built/12-citation.md" "2024-01-13" +"episodes/13-hosting.md" "c47ff180b5a80f5d864bde39faa89b49" "site/built/13-hosting.md" "2024-01-13" +"episodes/14-supplemental-rstudio.md" "b762f04d5306dfa51dce0d10342f802b" "site/built/14-supplemental-rstudio.md" "2024-01-13" +"instructors/instructor-notes.md" "595ad8f08c4edeed0e0fea6d99f3c6ae" "site/built/instructor-notes.md" "2024-01-13" +"learners/discuss.md" "ce3d3ad4146c026ef2fbf2697874970c" "site/built/discuss.md" "2024-01-13" +"learners/reference.md" "3f205209ed4d5580b7efbe7a676f0df2" "site/built/reference.md" "2024-01-13" +"learners/setup.md" "d550d9a13563fa02c6065493450dc24b" "site/built/setup.md" "2024-01-13" +"profiles/learner-profiles.md" "5fe5bf7537072422b91ed393ada03f9a" "site/built/learner-profiles.md" "2024-01-13" +"renv/profiles/lesson-requirements/renv.lock" NA "site/built/renv.lock" "2024-02-16" diff --git a/reference.md b/reference.md new file mode 100644 index 0000000000..61694fddc5 --- /dev/null +++ b/reference.md @@ -0,0 +1,79 @@ +--- +title: Git Cheatsheets for Quick Reference +--- + +## Git Cheatsheets for Quick Reference + +- Printable Git cheatsheets in several languages are [available here](https://github.github.com/training-kit/) ([English version](https://github.github.com/training-kit/downloads/github-git-cheat-sheet.pdf)). More material is available from the [GitHub training website](https://try.github.io/). +- An [interactive one-page visualisation](https://ndpsoftware.com/git-cheatsheet.html) + about the relationships between workspace, staging area, local repository, upstream repository, and the commands associated with each (with explanations). +- Both resources are also available in other languages (e.g. Spanish, French, and more). +- "[Happy Git and GitHub for the useR](https://happygitwithr.com)" is an accessible, free online book by Jenny Bryan on how to setup and use Git and GitHub with specific references on the integration of Git with RStudio and working with Git in R. +- [Open Scientific Code using Git and GitHub](https://open-source-for-researchers.github.io/open-source-workshop/) - A collection of explanations and short practical exercises to help researchers learn more about version control and open source software. + +## Glossary + +[changeset]{#changeset} +: A group of changes to one or more files that are or will be added +to a single [commit](#commit) in a [version control](#version-control) +[repository](#repository). + +[commit]{#commit} +: To record the current state of a set of files (a [changeset](#changeset)) +in a [version control](#version-control) [repository](#repository). As a noun, +the result of committing, i.e. a recorded changeset in a repository. +If a commit contains changes to multiple files, +all of the changes are recorded together. + +[conflict]{#conflict} +: A change made by one user of a [version control system](#version-control) +that is incompatible with changes made by other users. +Helping users [resolve](#resolve) conflicts +is one of version control's major tasks. + +[HTTP]{#http} +: The Hypertext Transfer [Protocol](#protocol) used for sharing web pages and other data +on the World Wide Web. + +[merge]{#merge} +: (a repository): To reconcile two sets of changes to a +[repository](#repository). + +[protocol]{#protocol} +: A set of rules that define how one computer communicates with another. +Common protocols on the Internet include [HTTP](#http) and [SSH](#ssh). + +[remote]{#remote} +: (of a repository) A version control [repository](#repository) connected to another, +in such way that both can be kept in sync exchanging [commits](#commit). + +[repository]{#repository} +: A storage area where a [version control](#version-control) system +stores the full history of [commits](#commit) of a project and information +about who changed what, when. + +[resolve]{#resolve} +: To eliminate the [conflicts](#conflict) between two or more incompatible changes to a file or set of files +being managed by a [version control](#version-control) system. + +[revision]{#revision} +: A synonym for [commit](#commit). + +[SHA-1]{#sha-1} +: [SHA-1 hashes](https://en.wikipedia.org/wiki/SHA-1) is what Git uses to compute identifiers, including for commits. +To compute these, Git uses not only the actual change of a commit, but also its metadata (such as date, author, +message), including the identifiers of all commits of preceding changes. This makes Git commit IDs virtually unique. +I.e., the likelihood that two commits made independently, even of the same change, receive the same ID is exceedingly +small. + +[SSH]{#ssh} +: The Secure Shell [protocol](#protocol) used for secure communication between computers. + +[timestamp]{#timestamp} +: A record of when a particular event occurred. + +[version control]{#version-control} +: A tool for managing changes to a set of files. +Each set of changes creates a new [commit](#commit) of the files; +the version control system allows users to recover old commits reliably, +and helps manage conflicting changes made by different users. diff --git a/setup.md b/setup.md new file mode 100644 index 0000000000..38d6a9f0e2 --- /dev/null +++ b/setup.md @@ -0,0 +1,51 @@ +--- +title: セットアップ +--- + +## Gitのインストール + +いくつかのCarpentriesのレッスンはGitに依存しているので、 +[ワークショップテンプレートのこのセクション][workshop-setup] を参照してください。 +様々なオペレーティングシステムにGitをインストールする手順があります。 + +- [Windows でのGit のインストール][workshop-setup] +- [MacOS でのGit のインストール][workshop-setup] +- [Linux でのGit のインストール][workshop-setup] + +## GitHub アカウントの作成 + +このレッスンのエピソード7と8には、 [GitHub](https://github.com)のアカウントが必要です。 + +1. https\://github.com にアクセスし、ウィンドウの右上にある「Sign Up」のリンクに従ってください。 +2. 指示に従ってアカウントを作成してください。 +3. GitHub でメールアドレスを確認する。 +4. 多要素認証を設定する（下記参照）。 + +### 多要素認証 + +2023年にGitHubは 、セキュリティを強化するためすべてのアカウントに [多要素認証(2FA)](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication)の設定を行うという要件を導入した。 +2FAを設定するためにいくつかのオプションがあります。 + +1. [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en\&co=GENIE.Platform%3DiOS\&oco=0)や [Duo Mobile](https://duo.com/product/multi-factor-authentication-mfa/duo-mobile-app) のような認証アプリを既に使っている場合は、 [そのアプリにGitHub を追加](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-totp-mobile-app) してください。 +2. スマートフォンにアクセスできるが、まだ認証アプリを使っていない場合は、認証アプリをインストールし、 [アプリにGitHubを追加](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-totp-mobile-app)してください。 +3. スマートフォンにアクセスできない場合、または認証アプリをインストールしたくない場合は、2つの選択肢があります： + 1. [テキストメッセージによる2FAの設定](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-text-messages) + ([SMSによる認証がサポートされている国のリスト](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/countries-where-sms-authentication-is-supported))、または + 2. [ハードウェアセキュリティキーを使用する](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-security-key) + [YubiKey](https://www.yubico.com/products/yubikey-5-overview/) + のように、または[Google Titanキー](https://store.google.com/us/product/titan_security_key?hl=en-US\&pli=1)を使用してください。 + +GitHubのドキュメンテーションに[2FAの設定に関する詳細](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication)があります。 + +*** + +## 作業ディレクトリの準備 + +`Desktop`フォルダーで作業を行うので、作業ディレクトリーを`Desktop`フォルダーに変更してください： + +```bash +$ cd +$ cd Desktop +``` + +[workshop-setup]: https://carpentries.github.io/workshop-template/install_instructions/#git