Summary and Setup

This Library Carpentry lesson introduces humanities scholars, educators, and public practitioners to essential open-source research tools. At the conclusion of the lesson you will be able to:

  • describe the basics of the Unix shell
  • explain why and how to use the command line
  • use shell commands to work with directories and files
  • use shell commands to find and manipulate data
  • Understand and use Git/GitHub
  • Use Git from the Unix Shell
Discussion

Be Excellent to Each Other

  • If you spot someone in the class who is struggling with something and you think you know how to help, please give them a hand. Try not to do the task for them: instead explain the steps they need to take and what these steps will achieve.

Software Setup

Discussion

Details

We will have time to do the setup, at least most of it, during the workshop.

The only thing that must be completed before the first day is to have a GitHub Account.

Shell

To participate in this Library Carpentry lesson, you will need a working Unix-like shell environment. We will be using Bash (Bourne Again Shell) which is standard on Linux and macOS. Some macOS users (Catalina or later) will have zsh (Z shell) as their default version. Even if you are a Windows user, learning Bash will open up a powerful set of tools on your personal machine, and familiarize you with the standard remote interface used on most servers and supercomputers.

The shell is a program that allows you to interact with your computer using typed text commands. It is the primary interface used on Linux and Unix-based systems, such as macOS, and can be installed optionally on other operating systems such as Windows.

Prerequisite

Terminal Setup

A terminal is the text-based interface that gives the user access to the shell of the operating system. Bash is the default shell on most Linux distributions and older versions of macOS. Windows users will need to install Git Bash to provide a Unix-like environment.

If you encounter issues, the Carpentries has a Configuration Problems and Solutions wiki page that may help.

Data Files

You need to download some files to follow this lesson:

Prerequisite

  1. Download shell-lesson.zip and move the file to your Desktop.

  2. Unzip/extract the file (ask your instructor if you need help with this step). You should end up with a new folder called shell-lesson on your Desktop.

  3. Open the terminal and type ls followed by the enter key.

    BASH 

    $ ls

    You should see a list of files and folders in your current directory.

  4. Then type:

    BASH 

    $ pwd

    This command will show you where you are in your file system, which should now be your home directory. In the lesson, you will find out more about the commands ls, pwd and how to work with the data in shell-lesson folder.

Python

Python is a very popular scripting programming language. We want to make sure we have it installed to use some packages that are built with python such as mystmd Here are steps to installing python:

Prerequisite

Installing Python

Git

Git is a version control tool used to track changes made on a project. Later was used for collaboration on projects as well

Prerequisite

Installing Git

Since several Carpentries lessons rely on Git, please see this section of the workshop template for instructions on installing Git for various operating systems.

GitHub

GitHub is a web-based platform that uses Git for version control and provides tools for collaboration on projects such as issue tracking and project progress tracking.

Prerequisite

Creating a GitHub Account

You will need an account for GitHub to follow this lesson.

  1. Go to https://github.com and follow the “Sign up” link at the top-right of the window
  2. Follow the instructions to create an account
  3. Verify your email address with GitHub
  4. Configure multifactor authentication (see below)
Discussion

Multi-factor Authentication

In 2023, GitHub introduced a requirement for all accounts to have multi-factor authentication (2FA) configured for extra security. Several options exist for setting up 2FA, which are summarised here:

  1. If you already use an authenticator app, like Google Authenticator or Duo Mobile on your smartphone for example, add GitHub to that app.
  2. If you have access to a smartphone but do not already use an authenticator app, install one and add GitHub to the app.
  3. If you do not have access to a smartphone or do not want to install an authenticator app, you have two options:
    1. set up 2FA via text message (list of countries where authentication by SMS is supported), or
    2. use a hardware security key like Yubikey or the Google Titan key.

The GitHub documentation provides more details about configuring 2FA.

VS Code

VS Code is a text editor with super powers that help programmers with their work by applying color schemes to text to help programmers follow syntactical and semantical rules. It also gives its users access to a terminal built in within it. And it can holf extentions that can be useful for different purposes. Example extentions: - GitLense - pdf viewer - GitHub Copilot

Prerequisite

Installing VSCode

Myst

Myst is a tool used to build and render interactive webpages easily using text files with a splash of markdown syntax (the arrangement of words and phrases to create well-formed sentences in a language)

Callout

Depending on how your python install went, you may need to use pip3 instead of pip

Prerequisite

Installing myst: