Introduction to Version and File Histories

What are files, and how can we work with them from the command line? How can we continue to work collaboratively?

From GUI to Command Line

Recap: The Command Line

We’ve learned how to:

• Create directories with mkdir in Linux/Unix or New-Item -ItemType Directory in PowerShell
• Navigate with cd and pwd OR Set-Location and Get-Location
• List contents with ls OR Get-ChildItem
• Create files with touch OR New-Item

But what exactly are files?

Now that we have seen how we can use the command line to create directories and files, and move them around, it might seem like a lot of work to do something we could do with a GUI. But the command line is actually much more powerful - we can search for text, count words, and manipulate files in ways that would be tedious with a GUI.

Introducing File Formats

The Many File Formats

There are many different file formats and each one has its own purpose. What constitutes a document or a file might seem obvious, but is actually a robust and ongoing scholarly debate in Library and Information Sciences (LIS) and Computer Science (CS).

What is a File? A Somewhat Reductive Answer

A file is a collection of data stored in a single unit, identified by a filename.

Files can be:

• Documents
• Images
• Videos
• Audio
• Any other collection of data

To put it a bit simply, a file is a collection of data stored in a single unit, identified by a filename. It can be a document, an image, a video, a sound, or any other collection of data.

File Extensions

The file extension is the part of the file name after the period.

Extension	Type
.docx	Microsoft Word document
.jpg	Image file
.mp3	Audio file
.txt	Plain text file
.md	Markdown file

The file extension tells the computer what type of file it is and what program to use to open it.

Proprietary vs Open Formats

Proprietary formats are owned by a company, like how Microsoft Word owns the format of .doc or .docx, which means a file with that extension can only be read in Word.

For example, a .docx file is a Microsoft Word document, a .jpg file is an image, and a .mp3 file is an audio file. Some file formats are proprietary, meaning they are owned by a company and can only be opened by certain programs. For example, .docx files can only be opened by Microsoft Word.

What is this?

Strange characters?

This gibberish is actually the code that makes up the file, but since the PDF Viewer doesn’t know how to read the code it just shows you the code itself rather than the data stored in the files. This is what happens when you try to open a Word document in a text editor - it shows the underlying code rather than the formatted document.

Proprietary All the Way Down

To be clear, .doc was invented in 1983 along with the first version of the software for Microsoft Word which ran on MS-DOS, whereas .docx was only introduced in 2007 as part of an XML-based update to the software.

History of Word

What Are Open Source File Formats?

Open source formats can be opened by many programs and are not owned by one company.

• .txt files work with any text editor
• .csv files work with any spreadsheet software
• Main benefit? More sustainable and portable

Other file formats are open source, meaning they are not owned by a company and can be opened by many different programs. For example, .txt files are plain text files that can be opened by any text editor. When we used the touch command, we told the terminal to create a .txt file. This is because .txt files are the simplest file format and only contain text.

Plain Text vs Formatted Text

A Word Document and a .txt file might look the same…

But Word contains hidden formatting that .txt does not.

In programming, we want to be explicit - so plain text is preferable.

As scholars working with computers, we need to be aware of the ways plain text and formatted text differ. While they might look similar, Word Documents contain a lot of hidden formatting that .txt files do not. Today, we have been talking a lot about text, from text commands to text files. But the core concept with both of these is the idea of plain text.

What is Plain Text? The Unicode Definition

According to the Unicode Standard:

Plain text is a pure sequence of character codes; plain Unicode-encoded text is therefore a sequence of Unicode character codes.

Key concept: Plain text shows if it is formatted or not (we call this markup), and usually contains no formatting.

This is a bit technical, but the key concept is that plain text shows if it is formatted or not (we call this markup), and usually contains no formatting.

Why Plain Text Matters

Plain text is:

• Portable - moves between programs easily
• Manipulable - responds to programmatic operations
• Sustainable - doesn’t require specific software

Edited in a text editor like VS Code

Plain text can be moved between programs more fluidly and can respond to programmatic manipulations. It is often manipulated in something called a text editor (like VS Code), which is a program that allows you to edit plain text files.

Example: Project Gutenberg

Pride and Prejudice by Jane Austen

Project Gutenberg is a website that hosts public domain books in plain text format. This is a great resource for working with text files.

Downloading Files from the Command Line

curl https://www.gutenberg.org/files/1342/1342-0.txt > pride-and-prejudice.txt

I can download this file directly from my terminal using the command line

The curl Command

• curl = “client URL” - downloads files from the internet
• > = redirect output to create a new file
• Result: a .txt file with the book’s text

The curl command is a command line tool for transferring data and downloading files from the internet. We can also use it to upload files. In this example, I’m using the command curl to download the book from Project Gutenberg. The > symbol tells the terminal to create a new file, store this data in the file, and save the file as pride-and-prejudice.txt. We can see that this file is a .txt file, meaning it is a plain text file. curl stands for “client URL” and is a command line tool for transferring data and downloading files from the internet. We can also use it to upload files to the internet.

Windows Alternatives

Using WSL or Git Bash:

wget https://www.gutenberg.org/files/1342/1342-0.txt > pride-and-prejudice.txt

Using PowerShell:

wget https://www.gutenberg.org/files/1342/1342-0.txt -OutFile pride-and-prejudice.txt

wget stands for “web get” and is a similar command line tool for retrieving and downloading files from the web. PowerShell requires slightly different syntax with the -OutFile flag.

Working with Text Files

Displaying File Contents

cat pride-and-prejudice.txt

cat = concatenate

• Displays the contents of a file
• For long files, you’ll only see the end without scrolling

The cat command stands for concatenate, and is a command line tool for displaying the contents of a file. For very long files like Pride and Prejudice, you’ll likely only see the end of the text without scrolling for ages.

Counting Words

wc -w pride-and-prejudice.txt

• wc = word count
• -w flag = count words
• Try it! How many words in Pride and Prejudice?

The wc command stands for word count. You’ll often notice that commands have flags like this, which are additional instructions for the command.

Counting Lines

wc -l pride-and-prejudice.txt

• -l flag = count lines
• Pride and Prejudice has 14,911 lines!

The -l flag tells the terminal to count the number of lines instead of words. This is useful for understanding the size of a text file.

Searching for Text

grep pride pride-and-prejudice.txt

grep output

The grep command allows us to search for specific words or patterns in a file. It returns all lines containing the search term.

Counting Occurrences

How many times does “pride” appear?

grep -c pride pride-and-prejudice.txt

Result: 43 times

Your turn: How many times does “prejudice” appear?

The -c flag with grep counts the number of matches instead of displaying them. This is useful for quick text analysis.

Command Summary

Command	What it does
curl / wget	Download files from the web
cat	Display file contents
wc -w	Count words
wc -l	Count lines
grep	Search for text
grep -c	Count occurrences

Introducing Markdown

What do you know about Markdown?

What is Markdown?

• A plain text file format (.md)
• Uses symbols to add formatting
• You’ve already seen it: README.md files!

Like .txt, but with lightweight formatting capabilities.

While .txt files are useful, in digital humanities we often use a file format called Markdown. Like txt, Markdown is a plain text file format that uses symbols to add formatting to the text.

Creating a Markdown File

touch is310-computing-humanities.md
# OR (PowerShell)
New-Item -ItemType File -Name is310-computing-humanities.md

Open in VS Code and add:

Computing in the Humanities is defined as the application of computational methods and tools to the study of humanistic questions.

We can create a Markdown file using the touch command and adding .md to the end of the file name.

Adding Bold Text

Put two asterisks on either side:

**Computing in the Humanities** is defined as ...

Renders as: Computing in the Humanities is defined as …

Maybe we want to highlight the word “Computing in the Humanities” in bold. To do this we would put two asterisks on either side of the word.

Adding Italics

Put one asterisk on either side:

**Computing in the Humanities** is *defined* as ...

Renders as: Computing in the Humanities is defined as …

We could also put defined into italics by putting one asterisk on either side of the word.

Adding Headings

Put a hashtag in front:

# Welcome to Computing in the Humanities

Different levels:

• # = Heading 1
• ## = Heading 2
• ### = Heading 3

We can add headings by putting hashtags in front of the text. More hashtags = smaller heading.

Previewing Markdown in VS Code

Markdown Preview

Click the preview icon in VS Code’s top right corner

We can see what this looks like in VS Code by using the Markdown Preview extension. This opens a preview of the Markdown file in a new tab.

Now you can see that our formatting has been applied to the text. This type of formatting is called Markdown syntax and it is a way of adding formatting to plain text files. What we did was exactly the same as what you do when you use the buttons in Word or Google Docs to add headers or styling to your text. The difference is that we are using symbols to add this formatting instead of buttons.

This may seem like a lot of extra work, but the advantages of Markdown are numerous.

Why Markdown? Advantage 1: Sustainability

Plain text is future-proof

• No license required
• No special software needed
• Works forever

Markdown is much more sustainable than Word or Google Docs. This is because the text is saved as plain text and not in a format that is optimized for editing. This makes it future-proof so that you don’t require a license or access to an application to see your files.

Why Markdown? Advantage 2: Platform Agnostic

Can be rendered by any text editor

• Works on Mac, Windows, Linux
• Works on web, desktop, mobile
• No vendor lock-in

Markdown can also be rendered by any text editor. This is because Markdown is a plain text format and not a rich text format. This makes it platform agnostic.

Why Markdown? Advantage 3: GitHub Integration

GitHub renders Markdown automatically

• README.md displays on repository pages
• Easy to share documentation
• Integrates with version control

Finally, Markdown plays nicely with Github, which renders it directly in your browser. This makes it easy to push up your files into your repositories.

Markdown: A Brief History

Markdown was created by John Gruber with Aaron Swartz in 2004.

Markdown: A Brief History

The goal was to create a file format that was easy to read and write, could be converted into web documents, and could be used by anyone. You can read more about the history of Markdown, in Bednarski, Dawid. “The History of Markdown: A Prelude to the No-Code Movement.” Taskade Blog, March 25, 2022. https://www.taskade.com/blog/markdown-history/.

It’s important to understand that Markdown has this history because many flavors of Markdown exist, and standardization of Markdown has been an ongoing project.

Markdown Flavors

Different Markdown implementations

This figure shows some examples of how Markdown is written depending on the platform and standards. Different platforms have added their own extensions to the basic Markdown syntax.

GitHub Flavored Markdown (GFM)

Created by GitHub in 2009

Adds features like:

• Tables
• Task lists
• Syntax highlighting
• Autolinks

GitHub Flavored Markdown Spec

GitHub Flavored Markdown is a superset of Markdown, meaning it adds additional features to Markdown. For example, GFM allows you to create tables in Markdown, which is not possible in regular Markdown.

CommonMark Markdown

CommonMark is another popular Markdown style and improvements to it are discussed in this repository https://github.com/commonmark/commonmark-spec/issues.

First Exercise

Currently, your README.md is your first assignment Init IS310 Homework. But what be some problems with this approach?

• README.md should indicate structure of repo, not be one assignment

init_is310

However, that is not very sustainable for the course since all your assignments will be in that folder. So, your first goal is to clean up your repository so that your first homework assignment has it’s own folder init_is310, which contains your initial README.md and any images.

Improve Your README.md

Then you will create a new README.md file in the root of your is310-coding-assignments that will be the main home page for your homework repository.

Try adding:

• A heading
• A subheading
• A bulleted list

Bonus: Add a link to our course website!

Now that you have a basic understanding of Markdown, let’s try improving the README.md file in your repository.

Helpful Resources

• GitHub Markdown Cheatsheet
• AI tools (GitHub Copilot, etc.)
• VS Code Markdown Preview

Push your changes to GitHub when done!

Homework: Lost & Found in the Cultural Command Line

Why a Cultural Data Maze?

This assignment has two goals:

1. Explore the cultural framing for your broader topic of interest
2. See how your group members each approach the same topic differently

Your maze should be themed around your cultural data topic of interest.

This assignment is designed to serve a dual purpose. First, it gives you practice with the command line skills we’ve been learning. But more importantly, it’s an opportunity to start thinking about the cultural data topic you’re interested in exploring this semester. By building a maze around your topic, you’ll begin developing the cultural framing for your work. And by solving your group members’ mazes, you’ll get to see how others in your group approach the same broad topic differently.

Part 1: Build a Maze About Your Cultural Data

Create a command line maze themed around your cultural data topic of interest for your group members to solve! First, you should create a new folder in your is310-coding-assignments repository called command-line-maze. Inside this folder, you should create a maze using directories and files.

For this assignment, you will be using your new mastery of the command line to create a maze for your group members to solve. Your maze should be themed around the broader cultural data topic you are interested in exploring this semester. For example, if you’re interested in the history of video games, your maze directories and files could reference game titles, developers, eras, or genres. You should work individually on this, though you are welcome to brainstorm ideas.

Maze Requirements

Your maze should have:

• A theme connected to your cultural data topic of interest
• An entrance and a solution
• At least 5 directories (can be nested)
• At least 5 files (can be nested)
• One hidden file or directory
• Clues to help solve the maze

Your directories, files, and clues should relate to the cultural data topic you are interested in exploring this semester. You are welcome to use Project Gutenberg for your files, but you can also use other files if you prefer. You can also use the command line to create your files, or use a text editor.

Documentation Required

Include a README.md in your maze folder:

• Instructions for solving the maze
• List of commands that might be helpful
• Your name and maze name as a header

Do NOT zip the README!

Be sure to not zip the README.md file, as we will need to read this file to solve the maze.

Zipping Your Maze

Mac/Linux/WSL:

zip -r path/to/your/zip/file path/to/your/directory

PowerShell:

Compress-Archive -Path "path\to\your\directory" -DestinationPath "path\to\your\zip\file"

Once you have created your maze, you should zip the folder that contains your maze. Be sure to replace these dummy file paths with your actual desired ones.

Submission

1. Upload zipped maze to your is310-coding-assignments repo
2. Post link in GitHub Discussion

Need inspiration? Try the example maze

If you need inspiration for your maze, take a look at the example maze which you can download and try solving.

Part 2: Solve Your Group Members’ Mazes

Once your maze is posted, solve at least two mazes from students in your group!

Steps:

1. Clone their repository
2. Navigate to the maze folder
3. Read the README.md (cat README.md)
4. Unzip the maze
5. Navigate and solve!

You are required to solve at least two mazes from other students in your group. This is an opportunity to see how your group members are approaching the same broad cultural data topic. Pay attention to the choices they made in their maze themes - it will help you understand different angles on your shared topic.

Unzipping

Mac/Linux/WSL:

unzip path/to/your/zip/file -d path/to/your/desired/directory

PowerShell:

Expand-Archive -Path "path\to\your\zip\file" -DestinationPath "path\to\your\desired\directory"

The -d flag or -DestinationPath just tells the terminal where to unzip the file. If you’re already in the correct spot, you can just use unzip or Expand-Archive with just the path.

Useful Commands for Solving

Command	Use Case
cd	Navigate through directories
ls	See what’s in each directory
ls -la	Find hidden files/directories
cat	Read file contents
pwd	Check current location

Your goal is to use both the command line cheatsheet and your preferred AI chatbot to solve the maze. You should be able to solve the maze in ~30 minutes.

When You Solve It

For each of the two mazes you solve:

1. Reply to their discussion post
2. Post a screenshot of your solved maze
3. Let them know you were successful!

Pay attention to how your group members framed their cultural data topic!

You need to do this for each of the two mazes you solve. Pay attention to how your group members approached the cultural data topic - you’ll start to see different perspectives on the same broad area of interest.

Additional Resources

Command Line

1. Introduction to the Bash Command Line - Programming Historian
2. Bash Basics Part 1
3. Beginner’s Guide to the Bash Terminal
4. The Most Important Thing You’ll Learn in the Command Line
5. CodeAcademy Command Line Course
6. Shell Scripting Tutorial

These resources provide additional depth on the command line if you want to continue learning beyond what we cover in class.

Questions?

Remember:

• Files = collections of data with extensions
• Plain text = portable, sustainable format
• Markdown = plain text with formatting
• Use curl/wget, cat, wc, grep for text work

See also: Command Line Cheatsheet