Updates for 2026

episodes/branches.md

@@ -25,7 +25,7 @@
 
 Branches are independent development lines. Working independently, you can likely get away with using git without creating any branches, as in the first diagram in the figure below. However, when you begin to work with others, branches allow team members to work on the code without impacting the work of other developers or users.
 
 ![These graph diagrams show repositories with different numbers of branches. The vertices, or circles, in these graphs show different commits, and each horizontal path is a branch. The first shows a repository with 1 main branch, the second a repository with 1 main and 1 feature branch, and the third repository 1 main and 2 feature branches.](../fig/branches/branches.png){alt='Graph diagram of nodes/circles and edges/arrows representing repository state. Each horizontal path is a branch. The first shows a single path representing a repository with a single main branch, the second has two branches, a main and a feature branch, and the third has three branches, a main and two feature branches.' width="75%"} 
 
 Branches can have a few different purposes. Branches created to develop a specific feature are referred to as feature branches, and are often short-lived. Branches can also be used for longer-term purposes, such as having separate development and production branches. How you organize and use branches in your project is referred to as a branching strategy, which we will cover more when we talk about git workflows.
 
@@ -50,9 +50,9 @@
 
 This will create the branch `my_new_branch` and move you to the new branch. If you run `git status` at this point it will display `On branch my_new_branch`. Making and committing any changes will only update `my_new_branch`.
 
 ![Creating a new branch. When you run `git checkout -b my_branch` your new branch gets created and checked out, meaning you are now on your new branch (represented by the star). Any commits you make will be on this branch until you checkout another one.](../fig/branches/create_branch.png){alt='Figure showing the process of creating a branch. From left to right: a repository with two commits on the main branch, followed by an arrow with the text "git checkout -b my_branch" followed by the same repository with the new feature branch added. A star is used on each repository to show which commit you are on, the first has it on the second commit in the main branch, the second on the first commit of the feature branch.' width="75%"}
 
 ![Every time you run the `git commit` command the commit will be added to your current branch.](../fig/branches/commit_branch.png){alt='Figure showing creating commits on a branch. From left to right: a repository with two commits on the main branch and one on a feature branch, followed by an arrow with the text "git commit (x2)", followed by the same repository with to additional commits on the feature branch. A star is used on each diagram to show where you are in the repository, each on the last commit on the feature branch.' width="75%"}
 
 The first time you push your branch to the remote repository, you will need to publish the branch by running run:
 
@@ -62,6 +62,14 @@
 
 After this any commits can be pushed with a simple `git push`.
 
+::::::::::::::::::::::::::::::::::::::::::  callout
+
+## Naming Branches
+
+Use short, descriptive names for your branches. Follow any branch naming conventions that your group has established.
+
+:::::::::::::::::::::::::::::::::::::::::::::::::::
+
 ### Changing Branches
 
 If you need to switch to another existing branch you can use the `git checkout` command. For example, to switch back to the main branch you can run:
@@ -72,7 +80,7 @@
 
 Remember, if you aren't sure which branch you are on you can run `git status`. It is good practice before you start making changes to any of your files to check that you are on the right branch with `git status`, particularly if you haven't touched the code recently.
 
 ![Switching branches using `git checkout`.](../fig/branches/checkout_branch.png){alt='Figure showing The process of changing, or checking out a branch. From left to right: a repository with two commits on the main branch and three on the feature branch with current location on the third commit of the feature branch, followed by an arrow with the text "git checkout main”, followed by the same repository with the current location now on the second commit in the main branch.' width="85%"}
 
 ### Merging Branches
 
@@ -85,7 +93,7 @@
 
 will merge any changes introduced to `main` into the `my_new_branch`. Merging in this direction is especially useful when you've been working on `my_new_branch` for a while and `main` has changed in the meantime.
 
 ![Merging new commits from the main branch into the feature branch with `git merge main`.](../fig/branches/merge_into_branch.png){alt='Figure showing the process of merging the main branch into the feature branch. On the top is a repository with a main and feature branch. The feature branch starts at the second commit on the main branch and has three commits, and the main branch has an additional two commits after the split. The current location is the third commit of the feature branch. Below is an arrow with the text "git merge main" followed by the same repository with a new arrow from the last commit on the main branch to a new commit on the feature branch, showing the changes from the main branch have been merged into the changes on the feature branch.' width="60%"}
 
 
 When development is complete on `my_new_branch`, it would be merged into `main`:
@@ -95,15 +103,41 @@
 git merge my_new_branch
 ```
 
 ![Merging new commits the feature branch into the main branch with `git merge my_branch`.](../fig/branches/merge_into_main.png){alt='Figure showing the process of merging the feature branch into the main branch. On the top is a repository with a main and feature branch. The feature branch starts at the second commit on the main branch and has three commits. The current location is on the second commit of the main branch. Below is an arrow with the text "git merge my_branch" followed by the same repository with a new commit on the main branch that has two incoming arrows from the main and feature branches, showing the changes from the feature branch have been merged into main branch.' width="50%"}
 
 Git will do its best to complete the merge automatically. For example, if none of the changes have happened in the same lines of code, things will usually merge cleanly. If the merge can't complete automatically, this is called a merge conflict. Any conflicts in the files must be resolved before the merge can be completed.
 
+### Using Branches
+
+In the Introduction we reviewed the basic git usage pattern that we usually start with when working independently. Let's add in these branching steps. The new steps are listed in bold.
+
+Let's assume we are working on a new feature or bug fix and have already cloned the repository.
+
+1. **Prepare to make changes:**
+    1. **Run `git status` to make sure you are on the main branch and don't have any uncommitted edits. Take care of anything left behind and return to the main branch with `git checkout main` as needed.**
+    2. **Run `git pull` on the main branch to stay up to date with the remote repository. This helps avoid merge conflicts later.**
+2. **Create a new branch with `git checkout -b branch_name`. Follow any naming conventions used by your group.**
+3. Make the changes you need to make.
+4. Commit your changes. This takes two steps:
+    1. `git add filename`: specify which files you'd like to include in the commit. Run `git status` for a reminder of what files have changed.
+    2. `git commit -m "Commit message"`: make the commit. Include a short but descriptive commit message.
+5. Push your changes to the remote repository with `git push`. **Your first push on this branch will need an additional flag: `git push --set-upstream origin my_new_branch`**
+6. Repeat steps 3-5 as needed.
+7. **If any changes have been introduced to main, merge those into your branch with:**
+```bash
+git checkout main
+git pull
+git checkout branch_name
+git merge main
+```
+8. **Merge your branch as needed. We will expand on this in the next two sections.**
+
+
 ## Merge vs Rebase
 
 There is another way to introduce changes from one branch to another: rebasing. A rebase rewrites history. For example, if there are new commits on the main branch while you are working on a feature branch, you could merge those commits into your feature branch, as we describe above. This creates a new commit with two parent commits: one in your feature branch, one in the main branch. Alternatively, you can rebase your feature branch onto the new end of the main branch with `git rebase main`. Rebasing "replays" your feature branch commits onto the new commits of the main branch, as if you started your branch there.
 
 ![Rebasing the feature branch onto new commits in the main branch with `git rebase main`.](../fig/branches/rebase.png){alt='Figure showing the process of rebasing the feature branch onto new commits in the main branch. On the top is a repository with a main and feature branch. The feature branch has three commits and starts from the second commit of the main branch, which has two additinal commits after the split. The current location is on the third commit of the feature branch. Below is an arrow with the text "git rebase main" followed by the same repository, but the feature branch now splits off the fourth and last commit of the main branch.' width="50%"}
 
 Rebasing creates a cleaner history, without the extra merge commit. However, rebases never be done on public branches that others might be using or even looking at. It will result in your repository and everyone else's having different history, which can be confusing and difficult to fix. If no one else is looking at your branch, especially if you haven't published it yet, rebasing is safe.
 

episodes/git-workflows.md

@@ -95,6 +95,15 @@ Using remotes, fetching and merging upstream changes frequently, and running com
 
 Now that you've chosen a workflow for your project, how do you communicate it? This is most often done with a CONTRIBUTING document. The CONTRIBUTING document describes the git workflow you are using, any conventions for branch naming that you have, and anything else a collaborator should know in order to contribute. It should be tailored to your project and team, and so it might also include how to run the tests for the project, requirements before creating Pull Requests, or perhaps detailed instructions for how follow the workflow if your team is less familiar with git. One of the goals of a CONTRIBUTING document is to lower the barrier to entry to contributing to a project and a good one will encourage collaboration.
 
+::::::::::::::::::::::::::::::::::::::::::  callout
+
+## AI Agent Configuration Files
+
+If your group is using AI Coding agents you should also include an Agent configuration file in your repository, such as [AGENTS.md](https://agents.md/), [CLAUDE.md](https://code.claude.com/docs/en/memory), or [copilot-instructions.md](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions). Work with your team to tailor this file to your project. Include in the file that you are following the guidelines in the CONTRIBUTING document.
+
+:::::::::::::::::::::::::::::::::::::::::::::::::::
+
+
 ## Enforcing your Workflow
 
 There are tools that you can use to make sure everyone follows the agreed upon workflow, which can make it easier to collaborate with others. First, you can add branch protections, which will enforce certain rules for certain branches. A common one is to not allow commits directly to the main branch, requiring changes to go through a Pull Request. There are many options for branch protection that you can read about on the [GitHub web page](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). Similarly, you can limit who on the team is able to push or merge changes into a particular branch, or in the entire repository. It is also a good idea to have testing and review requirements, particularly for production branches. These requirements and branch protections should be documented in the CONTRIBUTING document as well.

episodes/introduction.md

@@ -31,6 +31,27 @@ In this lesson we will be briefly going over some more advanced git tools that b
 
 While technology helps, it is not the solution on its own. We will also discuss git workflows, which describe the strategy of how branches and pull requests should be used to stay organized and productive. We will show a few common workflows, and give general guidance on how to choose what will work well for your project and team.
 
+## AI Coding Agents and Git
+
+AI coding agents can be used to be more productive than we could be on our own. Working in a git repository will make your AI coding agent even more productive. In a git repository it has the context of the history of the code and can see how it has evolved over time. It can look at file diffs (what has changed between versions), which is helpful for context and can help you write commit messages. Testing can be more efficient because your agent can more easily compare the results of the current version with the previous version.
+
+It is therefore just as important to have good version control and git practices, whether you are working with AI agents, human collaborators, both, or neither. AI agents can help: it can run git commands for you, write commit messages, and even make and review pull requests. You will, however, have to instruct your agent to do these things and so it is even more important for you to understand the process and know the best practices so you can make sure these are being followed. You can and should include these in your agent configuration files (CLAUDE.md, AGENTS.md, copilot-instructions.md), but be aware that your agent treats these as context, rather than rules to follow.
+
+::::::::::::::::::::::::::::::::::::::::::  callout
+
+## Agent Configuration Files
+
+To test the use of agent configuration files, I made a CLAUDE.md file in my repository, listing out the git best practices that I try to follow. I was disappointed to find that these were mostly ignored, even with a short CLAUDE.md file. The following was from a conversation with Claude where I asked why this was happening.
+
+> **Question**: The advice is to add a CLAUDE.md file to repositories so agents know how you like to work in the repo. But every time I try to test it with a new feature Claude ignores it and instead starts working. Is there something I am doing wrong?
+
+> **Answer**: Nothing wrong on your end — this is a known gap. CLAUDE.md gets read as background context during exploration (it's just another file among several I read to understand the codebase), so its prose gets absorbed as "useful info" rather than treated as a mandatory gate that has to fire before the first edit. Imperative instructions buried in markdown compete with everything else in context, and "read the rules" and "act on the rules" aren't the same event to me unless something forces the connection — which is exactly what happened here: I read the workflow section, then went straight to editing files without treating it as a checklist to execute.
+
+:::::::::::::::::::::::::::::::::::::::::::::::::::
+
+
+## Review
+
 Before diving in, we should review some basic terminology and commands. Note that while other options are available, we are focusing on GitHub for this lesson.
 
 - *repository (repo)*: The project, contains all data and history (commits, branches, tags).
@@ -46,6 +67,17 @@ Before diving in, we should review some basic terminology and commands. Note tha
 
 These definitions are adapted from [Code Refinery: Concepts around Collaboration](https://coderefinery.github.io/git-collaborative/concepts/).
 
+To use git and GitHub independently, we expect that you might follow this basic pattern:
+
+0. Clone the repository with `git clone URL`. You can retrieve the URL for the repository you will be working in by going to its page on GitHub. Click the green "Code" button and copy the URL that is displayed. You only need to do this once.
+1. If you cloned the repository previously run `git pull`.
+2. Make the changes you need to make (we will talk about branching in the next section).
+3. Commit your changes. This takes two steps:
+    1. `git add filename`: specify which files you'd like to include in the commit. Run `git status` for a reminder of what files have changed.
+    2. `git commit -m "Commit message"`: make the commit. Include a short but descriptive commit message.
+4. Push your changes to the remote repository with `git push`.
+5. Repeat steps 2-4 as needed.
+
 A note about git integrations: You may find that your IDE has git built in allowing you to use the GUI instead of running the commands we talk about here. In this lesson we are focusing on the command line git commands, since they should be universal across any system you use. After this lesson we encourage you to use what you are most comfortable with, and the commands we cover will also help you better understand the functionality of your IDE git integration.
 
 ## Activity