From 308d00e2dfd395cd28200478953c809e2e11069b Mon Sep 17 00:00:00 2001 From: Jarno Rantaharju Date: Tue, 2 Sep 2025 13:41:31 +0300 Subject: [PATCH] Add instructions for installing and using Git in VSCode. Refer to these in index. --- content/git-in-vscode.md | 319 +++++++++++++++++++++++++++++++++++++++ content/index.md | 9 +- 2 files changed, 326 insertions(+), 2 deletions(-) create mode 100644 content/git-in-vscode.md diff --git a/content/git-in-vscode.md b/content/git-in-vscode.md new file mode 100644 index 0000000..cbf63c2 --- /dev/null +++ b/content/git-in-vscode.md @@ -0,0 +1,319 @@ +(git-in-vscode)= + +# Git in VSCode + +This page is for setting up Git for VSCode. If you use a different IDE, try following +these instructions. If you are comfortable with the terminal, see {ref}`git-in-terminal`. + +Git is a version control system that lets you track who made changes to what +and when, and has options for updating a shared or public version of your code +on source code repository hosting platforms such as +[GitHub](https://github.com) or [GitLab](https://gitlab.com) or +[Bitbucket](https://bitbucket.org/). + +Please follow the installation, configuration, and verification instructions below. + + +## Installation + +`````{tabs} + ````{tab} Windows + + You can follow the steps below by watching the + [Carpentries video tutorial](https://www.youtube-nocookie.com/embed/339AEqk9c-8?modestbranding=1&playsinline=1&iv_load_policy=3&rel=0). + + - Download the [Git for Windows installer](https://gitforwindows.org/). + - Run the installer and follow the steps below: + 1. Click on "Next" four times (two times if you've previously + installed Git). You don't need to change anything + in the Information, location, components, and start menu screens. + 2. **From the dropdown menu select an editor**: + - Select VSCode from the list. You must have + VS Code installed already. + + After this, you don't have to do step 2 "selecting an editor" + step below (but that step lets you change your choice). + + - If you use a different different IDE, select that one if available. + Otherwise follow step 2 "selecting an editor" step below. + + 3. **On the page that says "Adjusting the name of the initial branch in new repositories", choose + "Override the default branch name for new repositories" and choose `main`. This will ensure + the highest level of compatibility for our lessons.** + 4. Ensure that "Git from the command line and also from 3rd-party software" is selected and + click on "Next". This ensures compatibility if with different text editors and the terminal. + 4. Choosing the OpenSSH executable: "Use bundled OpenSSH" and + click "Next". + 5. **Ensure that "Use the native Windows Secure Channel Library" is selected and click on "Next".** + 6. Ensure that "Checkout Windows-style, commit Unix-style line endings" is selected and click on "Next". + 7. **Ensure that "Use Windows' default console window" is selected and click on "Next".** + 8. Ensure that "Default (fast-forward or merge) is selected and click "Next" + 9. Ensure that "Git Credential Manager" is selected and click on + "Next". (if "Core" is an option, pick that) + + 10. Ensure that "Enable file system caching" is selected and click on "Next". + 11. Configuring experimental options: don't select either and + click "Next". + + 11. Click on "Install". + 12. Click on "Finish" or "Next". + + *Text copied and adapted from: [the Carpentries set up page](https://carpentries.github.io/workshop-template/#shell)* + ```` + + ````{tab} macOS + + **Install Git** for Mac + by downloading and running the most recent "mavericks" installer from + [this list](http://sourceforge.net/projects/git-osx-installer/files/). + Because this installer is not signed by the developer, you may have to + right click (control click) on the .pkg file, click Open, and click + Open on the pop up window. + After installing Git, there will not be anything in your `/Applications` folder, + as Git is a command line program. + See also the Git installation + [Carpentries video tutorial](https://carpentries.github.io/workshop-template/#shell-macos-video-tutorial). + + For older versions of OS X (10.5-10.8), use the + most recent available installer labelled "snow-leopard" + [available here](http://sourceforge.net/projects/git-osx-installer/files/). + + *Text copied and adapted from: [the Carpentries set up page](https://carpentries.github.io/workshop-template/#shell)* + ```` + + ````{tab} Linux + + If Git is not already available on your machine you can try to install it via + your distribution package manager. + + Open VSCode. In the toolbar open the "Terminal" menu and select "New Terminal". + + For Debian/Ubuntu run: + ```console + $ sudo apt-get install git + ``` + + For Fedora: + ```console + $ sudo dnf install git + ``` + + *Reference: [the Carpentries set up page](https://carpentries.github.io/workshop-template/#shell)* + ```` +````` + +--- + +(git-configuration)= + +## Configuration + +```{prereq} +We assume that you have: +- VSCode installed on your machine +- Git installed on your machine +``` + + +### Video instruction + +[This video (9 +min)](https://www.youtube.com/watch?v=WdDTp8NeHBs&list=PLpLblYHCzJACyKCfHnPwRruOxllNoHsEg) +shows how to configure Git. If you experience problems, +watch [this troubleshooting +video](https://www.youtube.com/watch?v=B27pUBrWp5w&list=PLpLblYHCzJACyKCfHnPwRruOxllNoHsEg). + +### Step 0: Start your terminal that has git + +Start Visual Studio Code. In the toolbar open the "Terminal" menu and select "New Terminal". + +This is a command line interface. You need to run a few commands to set up git. To run +a command, write it into the terminal and press Enter. + + +### Step 1: Setting user name and email + +First, the following commands will set your user name and email address: +```console +$ git config --global user.name "Your Name" +$ git config --global user.email yourname@example.com +``` + +If you are unsure which email to use, use the one that you have registered at +GitHub with. + +**This name and email will be public on GitHub when you make +contributions, including in this course.** If you prefer to not use a real email address but still want to make sure that +GitHub counts your contributions, you can use +`yourusername@users.noreply.github.com` (replace `yourusername`). + +This is important since your Git commits use this information. The `--global` +option uses this information for every repository for this user on +this computer. + +```{admonition} Different name/emails for different repositories +:class: dropdown + +If you need different name/email for different +repositories see [this StackOverflow question +for configuring based on +directory](https://stackoverflow.com/questions/4220416/can-i-specify-multiple-users-for-myself-in-gitconfig) +and [the raw configuration +options](https://git-scm.com/docs/git-config#_includes), including +something that works based on remote URLs (but it needs a newer +git version). +``` + + +### Step 2: Setting an editor + +You can skip this step if you already set it when installing git for Windows. + +This sets the text editor to git will use when called from the outside. + +```console +$ git config --global core.editor code +``` + +To set other editors, see {doc}`editors`. + + + +### Step 3: Set default branch + +You can skip this step if you already set it when installing git for Windows. + +The default branch on GitHub and GitLab is `main` but it used to be `master`. +In our workshop we will use `main` as the default branch also in the terminal +to be consistent with GitHub and GitLab: + +```console +$ git config --global init.defaultbranch main +``` + +This configuration will unfortunately have no effect on Git older than 2.28. +**But this is not a problem**. During the lesson we will have a workaround for +this. + + +### Step 4: Two more settings for Windows only + +You can skip this step if you already set it when installing git for Windows. + +We have found that these two settings prevent warnings and/or seeing no output +in some commands on Windows (no need to run these on macOS or Linux). At the +bottom of this page we motivate in more detail what these two do: + + +```console +$ git config --global core.autocrlf false +$ git config --global core.pager cat +``` + +--- + +## Verification + +```{prereq} +We assume that you have: +- VSCode installed on your machine +- Git installed on your machine +``` + +Before verifying, restart Visual Studio Code. + +The following shows the same steps that are shown in the video above. You can +see verification part in [the same video for configuration at +5:50](https://www.youtube.com/watch?v=WdDTp8NeHBs&t=350s). + + +### Step 1: Check your Git version + +Check your git version: + +Start Visual Studio Code. In the toolbar open the "Terminal" menu and select "New Terminal". +In the new terminal, run + +```console +$ git --version + +git version 2.39.2 +``` + +- We recommend at least 2.23. +- Ideal is 2.28 and newer. +- But the lesson and workshop will still work even with Git 2.0 + and we will add instructions/workarounds for Git below 2.28 or 2.23. + + +### Step 2: `git init -b main` inside a new folder + +Create a new example folder and open it. Select the git interface on the left side panel +and click "Initialize Repository". + + +### Step 3: Make a new file + +Create a new file called `example.txt`. Write some content into the file. + + +### Step 4: Stage the change + +Stage a newly made file `example.txt` before committing the change. Open the git section +in the side panel, find the file and click on the `+` button next to it. If the button is not +there, it will appear when you hover the mouse pointer over the filename. + + +### Step 5: Commit the change with a message + +Write a commit message such as "initial commit" in the text box above the file list. +Then click "Commit". + + +### Step 6: See the change history + +Open the file view in the left side panel. Select `example.txt` and click on "Timeline" +below the file list. You should see you commit in the timeline. Click on the commit to see +the changes you made. + +--- + +## Troubleshooting + +### Where is this configuration stored? + +To see where this information is stored (`--show-origin` works on git version +2.8 or greater only), use: +```console +$ git config --list --show-origin +``` + + +### On Windows `git log`, `git diff`, `git branch` or other git commands show no output at all + +It seems this can be fixed by these configuration settings: +```console +$ git config --global pager.log off +$ git config --global pager.diff off +$ git config --global pager.show off +$ git config --global pager.config off +$ git config --global pager.stash off +$ git config --global pager.help off +$ git config --global pager.blame off +$ git config --global pager.branch off +$ git config --global pager.annotate off +``` + +Following other manuals and documentation, it seems that all the above can be set with the following +(`cat` should be available within Git Bash but also PowerShell): +```console +$ git config --global core.pager cat +``` + + +### On Windows you see the warning "LF will be replaced by CRLF the next time Git touches it" + +Solution is to set this: +```console +$ git config --global core.autocrlf false +``` diff --git a/content/index.md b/content/index.md index 796e3a3..97cb481 100644 --- a/content/index.md +++ b/content/index.md @@ -34,8 +34,11 @@ several options on how to participate (below). We believe that **most learners will choose this option**. In this case we recommend two things: - {ref}`github` - - [Visual Studio Code](https://code.visualstudio.com/download) (or if you prefer, other {ref}`editors`) - - {ref}`git-in-terminal` + - [Visual Studio Code](https://code.visualstudio.com/download) + - {ref}`git-in-vscode` + + If you prefer you can use {ref}`editors`. Most of these do not come with Git integration, + so you would need to use Git from the terminal. ``` ```{grid-item-card} I want to use Git from a terminal, not from an editor @@ -63,6 +66,7 @@ several options on how to participate (below). 2: - {ref}`github` - [Visual Studio Code](https://code.visualstudio.com/download) (or if you prefer, other {ref}`editors`) + - {ref}`git-in-vscode` - {doc}`conda` ``` @@ -78,6 +82,7 @@ github vscode editors git-in-terminal +git-in-vscode ssh ```