import shutil, subprocess, sys

print(f"{'tool':<10}{'found at':<48}version")
print("-" * 78)
ok = True
for tool in ("git", "bash"):
    path = shutil.which(tool)
    if path is None:
        ok = False
        print(f"{tool:<10}{'NOT FOUND':<48}--")
    else:
        try:
            version = subprocess.run([tool, "--version"], capture_output=True,
                                     text=True).stdout.strip().splitlines()[0]
        except Exception:
            version = "(could not query)"
        print(f"{tool:<10}{path:<48}{version}")

print("-" * 78)
if ok:
    print("ready: the %%bash cells below will run.")
else:
    print("MISSING TOOL. Install Git (https://git-scm.com/downloads); on Windows,")
    print("launch Jupyter from Git Bash so that bash.exe is on PATH. The markdown")
    print("command blocks can still be read and typed into a terminal by hand.")

tool      found at                                        version
------------------------------------------------------------------------------
git       C:\Program Files\Git\clangarm64\bin\git.EXE     git version 2.54.0.windows.1
bash      C:\Program Files\Git\usr\bin\bash.EXE           GNU bash, version 5.3.9(1)-release (x86_64-pc-cygwin)
------------------------------------------------------------------------------
ready: the %%bash cells below will run.

working directory  --git add-->  staging area  --git commit-->  history

git config --global user.name "Your Name"
git config --global user.email "you@example.edu"
git config --global init.defaultBranch main
git config --global core.editor "code --wait"   # optional: VS Code
git config --list

%%bash
set -e
# Recreate an explicitly named, disposable demonstration directory.
mkdir -p generated
rm -rf -- generated/fd05_git_demo
mkdir generated/fd05_git_demo
cd generated/fd05_git_demo

# git's message carries an absolute path; keep the message, drop the prefix.
# Anchor on the prose, not on [^ ]*, which stops at a space in the path.
git init -b main | sed "s|in .*/generated/|in <...>/generated/|"
git config user.name "Demo User"
git config user.email "demo@example.com"
git config core.excludesFile "$(pwd)/.git/info/exclude"   # ignore user-level ignore files
git config core.autocrlf false                            # keep output platform-neutral
git status

Initialized empty Git repository in <...>/generated/fd05_git_demo/.git/

On branch main

No commits yet

nothing to commit (create/copy files and use "git add" to track)

%%bash
set -e
cd generated/fd05_git_demo

echo "# Demo project" > README.md
ls -a
git status

.

..

.git

README.md

On branch main

No commits yet

Untracked files:

  (use "git add <file>..." to include in what will be committed)

%%bash
set -e
cd generated/fd05_git_demo

git add README.md
git status
git commit -m "initial commit: README"
git --no-pager log

On branch main

No commits yet

Changes to be committed:

  (use "git rm --cached <file>..." to unstage)

	new file:   README.md

[main (root-commit) 999c8b0] initial commit: README

 1 file changed, 1 insertion(+)

%%bash
set -e
cd generated/fd05_git_demo

echo 'print("hello, class")' > hello.py
echo "Run: python hello.py" >> README.md

git status
git --no-pager diff

On branch main

Changes not staged for commit:

  (use "git add <file>..." to update what will be committed)

  (use "git restore <file>..." to discard changes in working directory)

	modified:   README.md

Untracked files:

  (use "git add <file>..." to include in what will be committed)

	hello.py

%%bash
set -e
cd generated/fd05_git_demo

git add .
git --no-pager diff --staged
git commit -m "add hello.py and usage line"
git --no-pager log --oneline

diff --git a/README.md b/README.md

index 54ffbc6..042f899 100644

--- a/README.md

+++ b/README.md

@@ -1 +1,2 @@

 # Demo project

+Run: python hello.py

diff --git a/hello.py b/hello.py

new file mode 100644

index 0000000..a6d8e57

%%bash
set -e
cd generated/fd05_git_demo

cat > .gitignore <<'EOF'
# Python and Jupyter caches
__pycache__/
*.py[cod]
.ipynb_checkpoints/

# Materialized environments
.venv/
venv/

# Data and generated outputs
data/
outputs/
*.parquet

# Secrets
.env
*.key
*.pem
EOF

cat .gitignore

# Python and Jupyter caches

__pycache__/

*.py[cod]

.ipynb_checkpoints/

# Materialized environments

.venv/

venv/

# Data and generated outputs

%%bash
set -e
cd generated/fd05_git_demo

mkdir -p __pycache__ data
touch __pycache__/hello.pyc data/big.parquet

git status
git check-ignore -v data/big.parquet
git add .gitignore
git commit -m "add .gitignore"
git --no-pager log --oneline

On branch main

Untracked files:

  (use "git add <file>..." to include in what will be committed)

	.gitignore

nothing added to commit but untracked files present (use "git add" to track)

.gitignore:11:data/	data/big.parquet

[main c1984e9] add .gitignore

 1 file changed, 18 insertions(+)

 create mode 100644 .gitignore

%%bash
set -e
cd generated/fd05_git_demo

git branch
git switch -c feature/greeting
echo 'print("greetings")' >> hello.py
git add hello.py
git commit -m "extend greeting on feature branch"
git --no-pager log --oneline

* main

Switched to a new branch 'feature/greeting'

[feature/greeting 6d46115] extend greeting on feature branch

 1 file changed, 1 insertion(+)

6d46115 extend greeting on feature branch

c1984e9 add .gitignore

1a606ce add hello.py and usage line

999c8b0 initial commit: README

%%bash
set -e
cd generated/fd05_git_demo

# meanwhile, main moves on too -- the histories now diverge
git switch main
echo "" >> README.md
echo "A demonstration repository for fd05." >> README.md
git add README.md
git commit -m "expand README"

git --no-pager log --oneline --graph --all

Switched to branch 'main'

[main 65d80c3] expand README

 1 file changed, 2 insertions(+)

* 6d46115 extend greeting on feature branch

| * 65d80c3 expand README

|/

* c1984e9 add .gitignore

* 1a606ce add hello.py and usage line

* 999c8b0 initial commit: README

%%bash
set -e
cd generated/fd05_git_demo

git merge feature/greeting --no-ff -m "merge feature/greeting"
echo "--- hello.py after the merge ---"
cat hello.py
echo "--- history ---"
git --no-pager log --oneline --graph --all

Merge made by the 'ort' strategy.

 hello.py | 1 +

 1 file changed, 1 insertion(+)

--- hello.py after the merge ---

print("hello, class")

print("greetings")

--- history ---

*   25f72be merge feature/greeting

|\

| * 6d46115 extend greeting on feature branch

import subprocess

REPO = "generated/fd05_git_demo"

def git(*args):
    """Run a git command inside the demo repository and return its stdout."""
    result = subprocess.run(["git", *args], cwd=REPO, capture_output=True,
                            text=True, check=True)
    return result.stdout

# Each line is "<commit> <parent1> <parent2> ...".  This is the edge list of G.
parent_c = {}
for line in git("log", "--all", "--format=%H %P").strip().split("\n"):
    fields = line.split()
    parent_c[fields[0]] = fields[1:]

short = lambda h: h[:7]

print(f"{len(parent_c)} commits\n")
print(f"{'commit':<10}{'parents':<22}subject")
print("-" * 64)
for c, parents in parent_c.items():
    subject = git("log", "-1", "--format=%s", c).strip()
    print(f"{short(c):<10}{' '.join(short(p) for p in parents):<22}{subject}")

6 commits

commit    parents               subject
----------------------------------------------------------------

25f72be   65d80c3 6d46115       merge feature/greeting
6d46115   c1984e9               extend greeting on feature branch

65d80c3   c1984e9               expand README

c1984e9   1a606ce               add .gitignore
1a606ce   999c8b0               add hello.py and usage line
999c8b0                         initial commit: README

def topological_order(parent_of):
    """List commits parents-first. Returns None if the graph has a cycle."""
    remaining = dict(parent_of)
    emitted, order = set(), []
    while remaining:
        ready = [c for c, ps in remaining.items() if all(p in emitted for p in ps)]
        if not ready:                      # nothing can be emitted: a cycle
            return None
        for c in sorted(ready):
            order.append(c)
            emitted.add(c)
            del remaining[c]
    return order

order = topological_order(parent_c)
print("topological order found:", order is not None)
assert order is not None, "the commit graph contains a cycle -- impossible"

position = {c: i for i, c in enumerate(order)}
violations = [(c, p) for c, ps in parent_c.items() for p in ps
              if position[p] > position[c]]
print(f"edges pointing backwards in the order: {len(violations)}   (must be 0)")
assert not violations
print(f"check passed: {len(order)} commits admit a topological order, so G is a DAG.")

topological order found: True
edges pointing backwards in the order: 0   (must be 0)
check passed: 6 commits admit a topological order, so G is a DAG.

def ancestors(commit, parent_of):
    """All commits reachable from `commit` by following parent edges, itself included."""
    seen, frontier = {commit}, [commit]
    while frontier:
        current = frontier.pop()
        for p in parent_of.get(current, []):
            if p not in seen:
                seen.add(p)
                frontier.append(p)
    return seen

def lowest_common_ancestors(a, b, parent_of):
    """Common ancestors of a and b that are not ancestors of another common one."""
    common = ancestors(a, parent_of) & ancestors(b, parent_of)
    return {c for c in common
            if not any(c in ancestors(other, parent_of) - {other} for other in common)}

merges = [c for c, ps in parent_c.items() if len(ps) == 2]
assert len(merges) == 1, f"expected exactly one merge commit, found {len(merges)}"
tip_1, tip_2 = parent_c[merges[0]]

ours = lowest_common_ancestors(tip_1, tip_2, parent_c)
assert len(ours) == 1, f"expected a unique merge base, found {len(ours)}"
ours = ours.pop()

theirs = git("merge-base", tip_1, tip_2).strip()

print(f"merged tips      : {short(tip_1)} and {short(tip_2)}")
print(f"our LCA          : {short(ours)}  ({git('log', '-1', '--format=%s', ours).strip()})")
print(f"git merge-base   : {short(theirs)}")
print(f"\nagree: {ours == theirs}   (exact hash comparison; tolerance 0)")
assert ours == theirs, "our merge base disagrees with git's"
print("check passed: two independent routes, one merge base.")

merged tips      : 65d80c3 and 6d46115

our LCA          : c1984e9  (add .gitignore)
git merge-base   : c1984e9

agree: True   (exact hash comparison; tolerance 0)
check passed: two independent routes, one merge base.

cd generated/fd05_git_demo
git remote add origin https://github.com/USER/REPO.git
git remote -v
git push -u origin main

my-project/
├── .gitignore
├── README.md           # purpose, and how to reproduce the results
├── environment.yml     # dependency specification
├── src/                # reusable code -- the mec_numerical of fd03
├── notebooks/          # exploration and exposition
├── data/               # inputs; often ignored, with retrieval instructions
├── outputs/            # regenerable tables and figures; often ignored
└── tests/              # automated checks -- fd04

%%bash
set -e
cd generated/fd05_git_demo

# your answer here

scratch/   # temporary working files
*.log

%%bash
set -e
cd generated/fd05_git_demo

# your answer here

%%bash
set -e
cd generated/fd05_git_demo

# your answer here

# your answer here

# Exercise 5 is done in a terminal, not here.
# Paste your pull-request URL below as a comment for your own records.

%%bash
set -e
cd generated/fd05_git_demo

printf 'Meeting notes: discount factors are dual variables.\n' > notes.md
git add notes.md
git commit -q -m "add notes.md"

rm notes.md
git add -A
git commit -q -m "delete notes.md"

echo "--- working tree after the deletion ---"
git status --short
echo "(clean: git has recorded the deletion)"
echo
echo "--- the commit that deleted the file ---"
git --no-pager log --oneline --diff-filter=D -- notes.md

--- working tree after the deletion ---

(clean: git has recorded the deletion)

--- the commit that deleted the file ---

6118706 delete notes.md

%%bash
set -e
cd generated/fd05_git_demo

# The deleting commit's PARENT still has the file: restore from <commit>^
deleting=$(git log --format=%H --diff-filter=D -- notes.md | head -1)
git restore --source="${deleting}^" -- notes.md

echo "--- restored contents ---"
cat notes.md
echo
git add notes.md
git commit -q -m "restore notes.md from history"
git --no-pager log --oneline -3

--- restored contents ---

Meeting notes: discount factors are dual variables.

883a5bf restore notes.md from history

6118706 delete notes.md

40a7a0f add notes.md

%%bash
set -e
cd generated/fd05_git_demo

printf 'scratch/   # temporary working files\n*.log\n' >> .gitignore
mkdir -p scratch
echo "scratch" > scratch/tmp.txt
echo "log line" > run.log

echo "--- git status ---"
git status --short
echo
echo "--- who ignores what? (|| true: exit status 1 just means 'not ignored') ---"
git check-ignore -v scratch/tmp.txt || echo "scratch/tmp.txt is NOT ignored"
git check-ignore -v run.log || echo "run.log is NOT ignored"

--- git status ---

 M .gitignore

?? scratch/

--- who ignores what? (|| true: exit status 1 just means 'not ignored') ---

scratch/tmp.txt is NOT ignored

.gitignore:20:*.log	run.log

%%bash
set -e
cd generated/fd05_git_demo

# Fix: put the comment on a line of its own.
grep -v '^scratch/   # temporary working files$' .gitignore > .gitignore.tmp
printf '# temporary working files\nscratch/\n' >> .gitignore.tmp
mv .gitignore.tmp .gitignore

echo "--- corrected tail of .gitignore ---"
tail -3 .gitignore
echo
echo "--- now who ignores scratch/tmp.txt? ---"
git check-ignore -v scratch/tmp.txt
echo
git status --short
git add -A
git commit -q -m "fix .gitignore comment placement"
echo "committed."

--- corrected tail of .gitignore ---

*.log

# temporary working files

scratch/

--- now who ignores scratch/tmp.txt? ---

.gitignore:21:scratch/	scratch/tmp.txt

 M .gitignore

committed.

%%bash
set -e
cd generated/fd05_git_demo

git switch -q -c conflict/left main
printf 'print("hello from the left branch")\n' > hello.py
git commit -q -am "left: rewrite greeting"

git switch -q -c conflict/right main
printf 'print("hello from the right branch")\n' > hello.py
git commit -q -am "right: rewrite greeting"

git switch -q conflict/left
echo "--- merging right into left: expect a conflict ---"
git merge conflict/right -m "merge right into left" || true
echo
echo "--- hello.py with conflict markers ---"
cat hello.py

--- merging right into left: expect a conflict ---

Auto-merging hello.py

CONFLICT (content): Merge conflict in hello.py

Automatic merge failed; fix conflicts and then commit the result.

--- hello.py with conflict markers ---

<<<<<<< HEAD

print("hello from the left branch")

=======

print("hello from the right branch")

%%bash
set -e
cd generated/fd05_git_demo

# Resolve by hand, keeping both changes.
cat > hello.py <<'EOF'
print("hello from the left branch")
print("hello from the right branch")
EOF

git add hello.py
git commit -q -m "merge right into left, keeping both greetings"

echo "--- resolved file ---"
cat hello.py
echo
echo "--- the merge commit and its parents ---"
git --no-pager log --oneline -1
git --no-pager log --pretty="%h has parents: %p" -1

--- resolved file ---

print("hello from the left branch")

print("hello from the right branch")

--- the merge commit and its parents ---

6a82ab3 merge right into left, keeping both greetings

6a82ab3 has parents: 2297762 379bd85

# the graph is still a DAG after the second merge -- re-run the section 7 checks
parent_c = {}
for line in git("log", "--all", "--format=%H %P").strip().split("\n"):
    fields = line.split()
    parent_c[fields[0]] = fields[1:]

merges = [c for c, ps in parent_c.items() if len(ps) == 2]
order = topological_order(parent_c)

print(f"commits: {len(parent_c)}   merge commits: {len(merges)}")
print(f"topological order still exists: {order is not None}")
assert order is not None, "a cycle appeared, which is impossible"
print("check passed: the history remains a DAG.")

commits: 13   merge commits: 2
topological order still exists: True
check passed: the history remains a DAG.

main_tip = git("rev-parse", "main").strip()
feature_tip = git("rev-parse", "feature/greeting").strip()

ours = ancestors(main_tip, parent_c) - ancestors(feature_tip, parent_c)

theirs = set(git("log", "--format=%H", "feature/greeting..main").strip().split("\n"))

print(f"{'commit':<10}subject")
print("-" * 52)
for c in sorted(ours, key=lambda h: -len(ancestors(h, parent_c))):
    print(f"{short(c):<10}{git('log', '-1', '--format=%s', c).strip()}")

print("-" * 52)
print(f"ours: {len(ours)} commits, git log feature/greeting..main: {len(theirs)} commits")
print(f"identical sets: {ours == theirs}   (exact hash comparison)")
assert ours == theirs, "our reachability computation disagrees with git"
print("check passed.")

commit    subject
----------------------------------------------------
2a3d05d   fix .gitignore comment placement
883a5bf   restore notes.md from history

6118706   delete notes.md
40a7a0f   add notes.md
25f72be   merge feature/greeting
65d80c3   expand README
----------------------------------------------------
ours: 6 commits, git log feature/greeting..main: 6 commits
identical sets: True   (exact hash comparison)
check passed.

# 1. a local repository
mkdir mec_sandbox && cd mec_sandbox
git init -b main
printf '# mec_sandbox\n\nScratch repository for fd05.\n' > README.md
printf '__pycache__/\n.ipynb_checkpoints/\n.venv/\ndata/\n.env\n' > .gitignore
git add README.md .gitignore
git commit -m "initial commit: project skeleton"

# 2. push to an EMPTY GitHub repository created in the browser first
git remote add origin https://github.com/USER/mec_sandbox.git
git push -u origin main

# 3. a branch, a licence, a pull request
git switch -c feature/license
curl -s https://api.github.com/licenses/mit | python -c \
    "import json,sys; print(json.load(sys.stdin)['body'])" > LICENSE
git add LICENSE
git commit -m "add MIT license"
git push -u origin feature/license
# then open the pull request on github.com, or: gh pr create --fill

# 4. after merging the PR in the browser
git switch main
git pull

# 5. read someone else's history
cd ..
git clone https://github.com/math-econ-code/mec_optim.git
cd mec_optim
git --no-pager log --oneline --graph --all | head -40

Place	What it contains	Main command
Working directory	the live files your editor sees	edit files
Staging area (the index)	the curated draft of the next snapshot	`git add`
Repository history	permanent, named snapshots	`git commit`

Command	Purpose
`git remote -v`	list remote names and URLs
`git fetch origin`	download remote history without integrating it
`git pull`	fetch and integrate remote work
`git push`	upload local commits
`git clone URL`	create a local copy of a remote repository

Git, GitHub, and the research toolchain¶

Alfred Galichon (NYU)¶

'math+econ+code' masterclass series: fundamentals of research in python¶

With bash code examples¶

Learning objectives¶

References¶

How to run this notebook¶

1. Motivation for version control¶

2. The Git data model¶

3. One-time setup¶

Which shell?¶

4. Live demonstration: creating a repository¶

First file, first commit¶

A second change, and `git diff`¶

5. `.gitignore`: what not to commit¶

6. Branches and merges¶

7. The commit history is a directed acyclic graph¶

8. Remotes and GitHub¶

9. Collaboration: the pull-request workflow¶

10. Environments and the research compendium¶

11. A project-start checklist¶

12. Summary¶

13. Exercises¶

14. Further directions¶

15. Solutions to the exercises¶

Solution to Exercise 1: Recover a deleted file¶

Solution to Exercise 2: Debug a `.gitignore`¶

Solution to Exercise 3: Create and resolve a merge conflict¶

Solution to Exercise 4: Acyclicity, proved and used¶

Solution to Exercise 5: Hello, GitHub¶

Git, GitHub, and the research toolchain¶

Alfred Galichon (NYU)¶

'math+econ+code' masterclass series: fundamentals of research in python¶

With bash code examples¶

Learning objectives¶

References¶

How to run this notebook¶

1. Motivation for version control¶

2. The Git data model¶

3. One-time setup¶

Which shell?¶

4. Live demonstration: creating a repository¶

First file, first commit¶

A second change, and git diff¶

5. .gitignore: what not to commit¶

6. Branches and merges¶

7. The commit history is a directed acyclic graph¶

8. Remotes and GitHub¶

9. Collaboration: the pull-request workflow¶

10. Environments and the research compendium¶

11. A project-start checklist¶

12. Summary¶

13. Exercises¶

14. Further directions¶

15. Solutions to the exercises¶

Solution to Exercise 1: Recover a deleted file¶

Solution to Exercise 2: Debug a .gitignore¶

Solution to Exercise 3: Create and resolve a merge conflict¶

Solution to Exercise 4: Acyclicity, proved and used¶

Solution to Exercise 5: Hello, GitHub¶

A second change, and `git diff`¶

5. `.gitignore`: what not to commit¶

Solution to Exercise 2: Debug a `.gitignore`¶