Introduction to Git: a hands-on workshop for Digital Humanities students

Introduction to Git A hands-on workshop for Digital Humanities students Arcangelo Massari <ar[email protected]> What we'll do today 01 Write a collaborative story together We'll create something while learning Git fundamentals through hands-on practice. 02 Learn essential Git skills Discover the core commands and workflows you'll use throughout your DHDK studies and beyond. 03 Understand why Git matters for DHDK See how version control connects to your coursework, research, and collaborative digital humanities projects. Don't worry if you've never used Git before, that's exactly why we're here. We'll start from the very beginning and build up your skills step by step. The problem Git solves Have you ever done this? Lost work from file overwrites Accidentally saved over an important version and couldn't get it back Forgotten what you changed Couldn't remember what modifications you made yesterday or last week Collaboration nightmares Struggled to merge work from multiple team members without conflicts Fear of experimentation Wanted to try new ideas but worried about breaking what already works Git solves all of these problems What is Git? Git is a time machine for your files Takes snapshots Git saves complete snapshots of your work (called 'commits') at any point in time Time travel capability You can go back to any previous snapshot whenever you need to Tracks all changes See exactly who changed what, when they changed it, and why Enables collaboration Multiple people can work on the same project without stepping on each other's toes You will use Git in almost every DHDK course Computational Management of Data Git is used to save different versions of Python code and collaborate with others in group projects. Information Modelling and Web Technologies Git is used for version control of web technologies like HTML, CSS, and JavaScript, and for team collaboration. Information Science and Cultural Heritage Git is used for version management of conceptual modeling of cultural heritage domains and ontology creation. Before we begin: technical setup 1Install Git on your computer We'll download and configure the core Git software that manages version control 2Create a GitHub account GitHub is where we'll store and share our collaborative work online 3Set up a text editor We'll use Visual Studio Code as our unified development environment Don't worry, we'll do this together, step by step. This setup process will take (hopefully) about 15 minutes, and I'll guide you through every single command and click. If you get stuck at any point, just raise your hand and I'll help you immediately. Step 1: Check if you have Git Before installing anything new, let's see if Git is already available on your system. 01 Open your terminal or command prompt Windows: Press Windows key + R, type cmd or search for "Command Prompt", press Enter Mac: Press Cmd + Space, type terminal, press Enter Linux: Open your terminal application (usually Ctrl + Alt + T) git --version 02 Type this command exactly Press Enter and look at the response ✓ Success If you see a version number like 'git version 2.39.0': you have Git installed! ⚠ Need to install If you see 'command not found' or similar error: we need to install Git Installing Git: All systems If you don't have Git installed, let's install it now. The process is straightforward and the same for all operating systems. 01 Navigate to the official Git website Go to: https://git-scm.com/downloads 02 Select your operating system Click on Windows, Mac, or Linux 03 Download and run the installer Download the installer for your system and run it when the download completes 04 Use default settings Click 'Next' or 'Continue' for all options. The defaults are perfectly fine for our needs 05 Verify installation Close and reopen your terminal, then check: git --version ⏱ This process typically takes about 5 minutes. If you encounter any issues during installation, raise your hand and we'll troubleshoot together. Special note for Mac users Mac users have an even easier installation option that's built right into the operating system! Try the built-in method first Open Terminal and type: git --version Mac will ask: "Install command line developer tools?" Click 'Install' and wait for it to finish Alternative method If the built-in method doesn't work, use the git-scm.com download method from the previous slide Both approaches work perfectly well D The built-in method installs Git along with other useful development tools that you might need for your DHDK coursework, so it's often the better choice. Installing VS Code Let's install VS Code together so everyone has the same development environment. 01 Download VS Code Go to: code.visualstudio.com Click 'Download' (it automatically detects your operating system) 02 Run the installer Run the installer when the download finishes Follow the installation steps and keep all the default options selected 03 Launch VS Code Open VS Code when installation is complete You should see a welcome screen with tabs for getting started ⏱ This installation typically takes about 5 minutes. VS Code will likely offer to install some recommended extensions . You can skip these for now, we'll focus on the basics today. Setup checklist: are we ready? Before we dive into our collaborative story exercise, let's make sure everyone has all the necessary tools properly installed and configured. 1 Git installed and working Type git --version in your terminal to verify You should see a version number, not an error message 2 Git configured with your identity Type git config --list to check your name and email are set Look for user.name and user.email in the output 3 GitHub account created and verified You should be able to log into github.com with your new account Check your email for the verification message if you haven't already 4 VS Code installed and opened VS Code should launch and show you a welcome screen or empty editor window Raise your hand if you need help with any of these! A collaborative story We're going to write a story together, and in the process, you'll learn all the essential Git skills you need for your DHDK courses. Creative collaboration Each person will contribute to the story, building on what others have written Real Git workflow We'll use authentic Git commands and processes that mirror professional development practices Practical learning By the end, you'll have hands-on experience with cloning, committing, pushing, pulling, and resolving conflicts DHDK preparation These exact skills transfer directly to your coursework in digital humanities projects Phase 1: Getting started In this first phase, we'll each get our own copy of the story repository. This process is called 'cloning'. It's how you download a complete Git repository to your local computer. 1 Clone the repository Download the story project to your computer 2 Navigate to the project Move into the project folder using the command line 3 Make your contribution Add your sentence to continue the story 4 Commit your changes Save your contribution with Git Follow these steps exactly as I demonstrate them. If you get stuck or see an error message, raise your hand immediately so I can help you get back on track. Step 1: Clone the repository Cloning creates a complete local copy of a Git repository on your computer. You'll have all the files, all the history, and full access to work with the project. 1Open your terminal Make sure you have a terminal or command prompt window open git clone https://github.com/arcangelo7/dhdk-story.git 2 Copy this command exactly Type or paste this command and press Enter 3 Watch it work Git will download the repository. You'll see progress messages This creates a new folder called "dhdk-story" on your computer D The URL tells Git where to find the repository on GitHub. The clone command copies everything: all files, all previous changes, and the complete project history. Step 2: Enter the folder Now we need to navigate into the project folder. In Git, you always need to be inside a repository folder to run Git commands on that project. cd dhdk-story Change directory The 'cd' command means 'change directory': it moves you into the specified folder Verify you're in the right place Your terminal prompt should now show that you're inside the dhdkstory folder You can type ls (Mac/Linux) or dir (Windows) to see the files This folder is now your local Git repository. Any Git commands you run will operate on this specific project. You can have many Git repositories on your computer, but you can only work on one at a time by being in its folder. Step 3: Open the story file Now let's see what we're working with! Open the story file to read the beginning and see where you'll add your contribution. 01 Open the folder in VS Code In your terminal, type: code . This opens the entire project folder in VS Code, allowing you to access all files 02 Trust the folder in VS Code When opening a folder for the first time, VS Code often starts in Restricted Mode. You will see a prompt asking if you trust the authors of the files in this folder. Click "Yes, I trust the authors" to enable full editing capabilities. 03 Read the story beginning You'll see our story starter: "The group chat exploded: 47 unread messages. 'Who deleted the shared folder?' 'It wasn't me!' 'The deadline is in 3 hours!' Then came the message that changed everything: 'I have a backup. But...'" 04 Plan your contribution Think about what happens next. You'll add ONE sentence to continue the story D If the code command doesn't work, you can also open VS Code manually and use File → Open Folder to navigate to the dhdk-story folder and open it. Step 4: Add your sentence Add your contribution to the story and experience how Git tracks changes. 01 Position your cursor Click at the end of the existing text in the story.txt file Press Enter to create a new line 02 Write your sentence Add ONE creative sentence that continues the story Be imaginative. What happens next? 03 Save the file Press Ctrl+S (Windows/Linux) or Cmd+S (Mac) to save Keep VS Code open. We'll use it again soon D Notice that VS Code shows you the file has been modified. You might see a dot next to the filename or a colored indicator. This visual feedback helps you track what you've changed. Step 5: Tell Git about your change Now comes the important part: saving your changes with Git. This is a two-step process that gives you control over exactly what gets saved and when. git add story.txt 1Stage your change This tells Git: "I want to include this file in my next commit" Staging lets you choose exactly which changes to save git commit -m "Added my sentence to the story" 2Commit your change This creates a permanent snapshot with a descriptive message The message explains what you did. Always use clear, descriptive messages! ⚠ The quotation marks around the commit message are required! Git needs them to know where the message starts and ends. You've just made your first Git commit. This change is now saved in your local Git repository with your name, timestamp, and description attached. Phase 2: Working together Now the real collaboration begins! Everyone has made changes to their local copy of the story, but these changes exist only on your individual computers. In this phase, we'll learn how to share our work with the team and handle the challenges that arise when multiple people modify the same files. 1 Share changes (git push) Upload your local commits to GitHub so others can see them 2 Get others' changes (git pull) Download and integrate changes that teammates have made 3 Resolve conflicts Handle situations where multiple people changed the same parts of files This phase will teach you about pushing, pulling, and merge conflicts. Getting our first conflict Watch what happens when I follow Git's suggestion: git pull hint: You have divergent branches and need to specify how to reconcile them. hint: You can do so by running one of the following commands sometime before hint: your next pull: hint: hint: git config pull.rebase false # merge hint: git config pull.rebase true # rebase hint: git config pull.ff only # fast-forward only hint: hint: You can replace "git config" with "git config --global" to set a default hint: preference for all repositories. You can also pass --rebase, --no-rebase, hint: or --ff-only on the command line to override the configured default per hint: invocation. This message appears because you have local changes (your work on the story.txt file) that conflict with changes on the remote repository. Git detects that your local branch has diverged from the remote 'origin/main' branch and needs instruction on how to combine these changes. For this workshop, we will choose the "merge" option, which means we want Git to attempt a merge of the divergent histories. We'll set this preference by running git config pull.rebase false. Understanding divergent branches Explain what this Git message means and why it appears: What are divergent branches? You made changes to your local copy of the story Someone else made different changes to the shared version on GitHub Git doesn't know how to automatically combine these different versions The three options Git offers: 1 git config pull.rebase false (merge) - RECOMMENDED FOR BEGINNERS Keeps both versions of the history Creates a "merge commit" that shows when the two versions were combined Safe and preserves all work 2 git config pull.rebase true (rebase) Rewrites history to make it look like your changes came after theirs More advanced technique, can be confusing for beginners Makes a cleaner history but harder to understand what happened 3 git config pull.ff only (fast-forward only) Only works when there are no conflicts Will fail in our current situation since we have conflicting changes Most restrictive option For this workshop: We'll use option 1 (merge): git config pull.rebase false This is the safest approach and shows exactly how collaboration happened. What a conflict looks like in your file When Git encounters a conflict, it modifies your file to show you both versions. Let's examine exactly what these conflict markers mean. <<<<<<< HEAD Your version of the text here... ======= The other person's version here... >>>>>>> origin/main Conflict markers explained Between <<<<<<< HEAD and ======= YOUR version of the conflicting content "HEAD" refers to your current local changes Between ======= and >>>>>>>> The OTHER person's version from GitHub "origin/main" refers to the remote repository The markers themselves The <<<<<<<, =======, and >>>>>>> symbols are added by Git You must remove ALL these markers when resolving Your job is to decide what the final version should look like, edit the file to reflect that decision, and remove all the conflict markers. Resolving the conflict step by step Now watch me demonstrate this exact process. I'll resolve the conflict between my changes and the volunteer's changes by following the steps we just discussed. 1 Open story.txt in VS Code I can see the conflict markers with both versions displayed VS Code highlights the conflicted sections visually 2Analyze both versions I read both sentences and decide how to combine them I'll keep both contributions since they both add value to the story 3 Edit and clean I remove all the conflict markers I arrange the sentences so they flow naturally I save the file 4 git add story.txt git commit -m "Resolve conflict" Complete the merge 5 git push Share the resolution ✓ Success! Now everyone can see the merged version Now it's your turn to resolve conflicts Everyone will now experience resolving a merge conflict firsthand. This is the most challenging part of today's workshop, but also the most valuable skill you'll learn. Everyone: type git pull You'll get conflicts too! Here's why: You have local changes Your sentence that you committed earlier The repository has different changes The volunteer's sentence plus my resolution Git needs your decision How should your sentence fit with the existing story? 01 Follow the resolution steps Open story.txt in VS Code and find the conflict markers 02 Make creative decisions Decide how to integrate your sentence with the existing story 03 Complete the resolution Remove markers, save, add, commit Note: You should NOT do git push in this case. You don't have permission to contribute to this repository, and for simplicity, we can't give permissions to everyone. The important thing is that you learn to resolve the conflict locally. Phase 3: Forks and pull requests We've learned the basics of direct collaboration, but there's an even more powerful and safer way to work together: forks and pull requests. This approach is used by virtually all major open-source projects and many professional development teams. Problem with direct access Giving everyone write access to a repository can be risky. Anyone could accidentally break or delete important work Solution: Forks Everyone gets their own complete copy of the repository where they can experiment freely Propose changes When ready, contributors propose their changes through "pull requests" for review and discussion Quality control Repository maintainers can review, discuss, and selectively merge the best contributions What is a fork? A fork is your personal, complete copy of someone else's repository. Think of it as getting your own private workspace where you can experiment without any risk to the original project. Original repository Stays completely safe and unchanged Only authorized maintainers can directly modify it Your fork Belongs entirely to you. You can do anything! Experiment, break things, try new ideas safely When ready Propose merging your best changes back to the original This proposal is called a "Pull Request" Forking is how you contribute to any open-source project on GitHub, from major software like Linux and Python to digital humanities tools and datasets. It's a fundamental skill for participating in the broader scholarly and technical community. Let's fork the repository Now everyone will create their own fork of our story repository. This gives each of you complete creative control over your own version. 01 Navigate to the original repository Go to: github.com/arcangelo7/dhdk-story Make sure you're looking at the original, not your local folder 02 Click the Fork button Look for the 'Fork' button in the top right corner of the repository page Click it to start the forking process 03 Choose your account GitHub will ask: "Where should we fork this repository?" Select your own GitHub account as the destination 04 Wait for completion GitHub takes a few seconds to create your complete copy You'll be redirected to YOUR version: github.com/[YOURUSERNAME]/dhdk-story Clone your fork Important: Now we need to work on YOUR fork, not the original repository. This ensures you have complete control over your contributions. 01 Go to YOUR fork Navigate to: github.com/[YOURUSERNAME]/dhdk-story Make sure the URL shows YOUR username, not "arcangelo7" 02 Copy the clone URL Click the green "Code" button and copy the HTTPS URL from YOUR fork cd .. 03 Navigate in terminal This moves you back one folder level git clone https://github.com/[YOUR-USERNAME]/dhdk-story.git dhdkstory-fork 04 Clone your fork Replace [YOUR-USERNAME] with your actual GitHub username cd dhdk-story-fork 05 Enter your fork Now you're working in your own independent copy where you can make any changes you want! Make changes on your fork This is your creative playground! Since it's your fork, you can make any changes you want without worrying about breaking anyone else's work. 01 Open your story Open story.txt in VS Code from your fork directory You'll see the current version of our collaborative story 02 Add your creative contribution Add one sentence to continue the story in your own style 03 Save your work Save the file in VS Code git add story.txt git commit -m "Added my continuation to the story" 04 Commit to your fork git push 05 Push to YOUR repository This works smoothly because you own this repository! Remember Git is here to help you, not frustrate you You can download today's workshop slides from Zenodo: 10.5281/zenodo.17273051 Questions about today's workshop? Contact information for follow-up help Email: [email protected]