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
Prerequisite

Prerequisites

  1. To complete this lesson, you will need a Unix-like shell environment (see Setup). You will also need to download the file shell-lesson.zip from the lesson website to your desktop and extract it there (once you have unzipped/extracted the file, you should end up with a folder called “shell-lesson”).
  2. Setup a GitHub account
  3. Install git on your own computer
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.

  • Windows: There are also some more advanced solutions available for running Bash commands on Windows. A Bash shell command-line tool is available for Windows 10, which you can use if you enable the Windows Subsystem for Linux. You can also run Bash commands on a remote computer or server that already has a Unix Shell from your Windows machine. This can be done through a Secure Shell (SSH) client. One client available for free for Windows is PuTTY.

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

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

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.

Git

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.

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.

Prerequisite

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

Here are installation instructions for VS Code: ::: tab ### Windows Download the windows installer for windows and run it

Linux

  • Download the debian-based distribution
  • Run the install through the graphical software center if it’s available
  • Or use the commandline to run it:
sudo apt install ./<file>.deb

Mac OS

  • Download Visual Studio Code for macOS.
  • Open the browser’s download list and locate the downloaded app or archive.
  • If archive, extract the archive contents. Use double-click for some browsers or select the ‘magnifying glass’ icon with Safari.
  • Drag Visual Studio Code.app to the Applications folder, making it available in the macOS Launchpad.
  • Open VS Code from the Applications folder, by double clicking the icon.
  • Add VS Code to your Dock by right-clicking on the icon, located in the Dock, to bring up the context menu and choosing Options, Keep in Dock.
  • Launch VS Code from the c

::::::::::::::

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: ::: tab ### Windows

This requires having python package installer - Confirm you have Python installed in your system and Python Package Installer pip

python -v
pip -v

If you get an output from these two commands then you have these two packages installed - On your shell terminal run:

pip install mystmd

Linux

This requires having python package installer Confirm you have Python installed in your system and Python Package Installer pip

python -v
pip -v

If you get an output from these two commands then you have these two packages installed

On your shell terminal run:

pip install mystmd

Mac OS

This requires having python package installer - Confirm you have Python installed in your system and Python Package Installer pip

python -v
pip -v

If you get an output from these two commands then you have these two packages installed - On your shell terminal run:

pip install mystmd

::::::::::