Git - jonathancolmer/lab-guide GitHub Wiki

Introduction to Git and GitHub

What They Are

  • Git – a version control system for tracking changes in files over time.
  • GitHub – an online platform that hosts Git repositories and adds collaboration/project management features.
  • Git Client – software (GUI or command line) that lets you use Git without typing all commands manually.

Why Use Git?

Git solves common file management problems:

  • Replaces messy file naming like final_reallythistime_v99.doc.
  • Tracks changes, authorship, and timestamps automatically.
  • Prevents lost files and conflicting edits.
  • Keeps a full history so you can revert to earlier versions.

Roles in GitHub

  • Observer – views code, provides feedback (often a PI who doesn’t code).
  • Contributor – edits code following maintainer’s guidance (RAs, coding PIs).
  • Repo Maintainer – enforces standards, reviews contributions, manages repo.

Key Concepts and Actions

Repository (Repo)

A project folder tracked by Git, hosted locally and/or on GitHub.

Fork

Your own copy of another repo on GitHub — lets you make changes without affecting the original.

Clone

Download a repo to your local machine, keeping the link to the original for syncing changes.

Cloning from GitHub:

  1. Go to the repo page.
  2. Click the green <> Code button.
  3. Choose “Open with GitHub Desktop” or “Download ZIP.”
  4. Select a local folder (never clone into an active shared folder with multiple Git users).

Dropbox caution: If multiple people run Git inside the same Dropbox folder, Git’s internal files can be corrupted. Only use shared folders if you are the sole Git user in that folder.

Branch

A separate workspace within the repo for your changes. Keeps main branch stable.

Creating a branch:

  1. Select “Branch” under the repo name.
  2. Click “New Branch.”
  3. Name it after yourself or the task.
  4. Make changes here before merging.

Commit

A saved snapshot of your changes with a message describing what was done.

Best practices:

  • One commit = one logical change.
  • Use imperative verbs: “Add regression script,” not “Added…”.
  • Keep messages short and clear.
  • Never commit raw/confidential data or large binary files — add them to .gitignore.

Pull Request (PR)

A request to merge your branch changes into the main branch.

Making a PR:

  1. Go to “Pull Requests” in the repo.
  2. Click “New Pull Request.”
  3. Select main as the base, your branch as compare.
  4. Review changes, add a description, and submit.

Repository Hygiene

README.md

Include:

  • Project description.
  • How to install/run code.
  • Data sources and access instructions.
  • Contact information.
  • Known issues/pending tasks.

Use the AEA Data Editor’s README template.

.gitignore

Tells Git which files/folders not to track.

Generate templates at gitignore.io.

Licensing

Without a license, others cannot legally reuse your code.

  • Code – MIT, GPL, Apache 2.0, or lab’s default Modified BSD.
  • Data/docs – Creative Commons (CC-BY 4.0 preferred).

See choosealicense.com for guidance.

Good Practices

  • Decide roles (maintainer, contributors) before starting.
  • Agree on a workflow and repo structure.
  • Keep repos clean — commit only what’s necessary.
  • Have all pull requests reviewed before merging.
  • Delete branches after merging to keep things tidy.

Further Resources