Git basics

1. Why Git matters¶

Git helps you track how your SDS320 project changes over time. This is useful for backup, documentation, transparency and Reproducibility.

Your final project should include a public GitHub or GitLab Repository. The repository should make it possible for another student to understand what you did, which files matter, how your workflow is organised and how the main results can be reproduced.

This page gives you a practical Git refresher for SDS320. It focuses on the basic workflow you need during the semester. For detailed expectations about the final project repository, see Repository.

2. The basic idea¶

Git records snapshots of your project. These snapshots are called commits.

A Git workflow usually follows this pattern:

work on files
→ check what changed
→ stage selected changes
→ commit with a message
→ push to the online repository

In SDS320, Git is not only a technical tool. It also helps you show project development. Your commit history can document when you added data notes, tested preprocessing, improved figures, fixed path problems or updated your report.

3. Key Git concepts¶

Repository¶

A repository is a project folder tracked by Git. It usually contains notebooks, scripts, documentation, environment information and selected outputs.

In SDS320, your assessed project repository should be understandable to someone who did not sit next to you while you worked.

Commit¶

A commit is a saved snapshot of selected changes. A good commit should represent one meaningful step, not a random collection of unrelated edits.

Examples of useful commit moments:

• adding an initial README,

• creating the first data inventory,

• testing data loading,

• fixing a coordinate reference problem,

• adding a preprocessing notebook,

• improving a figure,

• documenting a limitation.

Staging¶

Staging means selecting which changed files should go into the next commit. This lets you commit related changes together.

Remote repository¶

A remote repository is the online version of your project, for example on GitHub or GitLab.

Your local repository lives on your computer. The remote repository makes it possible to back up, share and submit your work.

4. Recommended Git workflow¶

Use this workflow regularly while working on your project.

1. Check what changed¶

Run this inside your project folder:

git status

This shows which files were changed, added or deleted.

2. Stage meaningful files¶

To stage all current changes:

git add .

For more controlled commits, stage selected files:

git add README.md
git add notebooks/01_explore_data.ipynb
git add scripts/preprocessing.py

3. Commit with a clear message¶

git commit -m "Add initial data inventory"

A good commit message describes the change clearly.

4. Push to the remote repository¶

git push

This uploads your committed changes to the online repository.

5. Pull before continuing on another machine¶

If you work on more than one computer, update your local copy first:

git pull

This downloads changes from the remote repository.

5. Starting a repository¶

There are two common ways to start.

Option A: start online first¶

This is often easiest for beginners.

1. Create a new repository on GitHub or GitLab.

2. Copy the repository URL.

3. Clone it to your computer:

git clone <repository-url>

1. Move into the folder:

cd <repository-folder>

1. Add or copy your SDS320 project files into this folder.

Option B: start locally first¶

If you already have a local project folder, open a terminal in that folder and run:

git init

Then connect it to an online repository later.

6. Using Git in VS Code¶

You can use Git from the Command Line, but many students find the VS Code interface easier for everyday work.

VS Code has a Source Control view that lets you inspect changes, stage files, write commit messages, commit changes and sync with a remote repository. It still uses the Git installation on your computer, so git --version must work first.

A. Open the right folder¶

Open the full project folder in VS Code, for example:

sds320/project/

Do not open only a single notebook. Opening the full folder lets VS Code detect the repository, show changed files and manage relative paths more clearly.

B. Use the Source Control view¶

In VS Code:

1. open the Source Control view in the left sidebar,

2. inspect the list of changed files,

3. click a file to see what changed,

4. stage the files that belong together,

5. write a short commit message,

6. commit the changes,

7. sync or push the commit to GitHub/GitLab.

C. Recommended VS Code extension¶

If you use GitHub, install the official GitHub Pull Requests and Issues extension.

From the VS Code Extensions panel, search for:

GitHub Pull Requests and Issues

Or install it from the terminal:

code --install-extension GitHub.vscode-pull-request-github

This extension is useful when you want to review changes, manage pull requests or connect issues to code. For a simple individual SDS320 project, the built-in Source Control view is usually enough.

D. Using VS Code vs. the terminal¶

You can use both. The important part is that you understand the basic workflow: check, stage, commit, push.

7. Repository contents¶

What should go into your repository¶

Your SDS320 repository should usually include:

• README.md,

• notebooks,

• scripts,

• an Environment File,

• small configuration files,

• data download instructions,

• small example data if permitted,

• figures or outputs that help explain the result,

• report material if appropriate.

The repository should make your workflow understandable and rerunnable.

For more detailed expectations, see Repository.

What should not go into your repository¶

Avoid committing:

• very large raw data files,

• private or sensitive data,

• access tokens,

• passwords,

• API keys,

• local cache folders,

• temporary files,

• system files such as .DS_Store,

• outputs that are huge or easy to recreate.

Use a Gitignore File to exclude files that should not be tracked.

Example .gitignore:

# system files
.DS_Store
Thumbs.db

# Python
__pycache__/
*.pyc

# environments
.venv/
.env

# large/local data
data/raw/
data/interim/

# temporary outputs
*.tmp

8. Good commit messages¶

Useful commit messages are short and specific.

A good commit message helps you and others understand the project history.

Use this pattern when you are unsure:

Verb + object + context

Examples:

Add preprocessing notebook
Fix broken relative paths
Update README with data source notes
Save first evaluation figure
Document model limitation

9. Flags & checks¶

Use this table when your Git workflow becomes confusing. Start with the first check before changing many things at once.

For technical problems, see Troubleshooting.

10. Mini task¶

Work inside your SDS320 project folder.

Complete this checklist:

• Open the full project folder in VS Code.

• Check that Git is available with git --version.

• Check the current state with git status.

• Add or update README.md.

• Add or update environment.yml.

• Add or update .gitignore.

• Stage the related files.

• Commit them with a meaningful message.

• Push the commit to your remote repository.

• Open the online repository and confirm that the files appear there.

Example terminal workflow:

git status
git add README.md environment.yml .gitignore
git commit -m "Add initial project documentation files"
git push

Write one sentence in your project notes:

My next useful Git commit will be: ...

11. Key takeaways¶

• Git records the development of your project over time.

• Commit regularly after meaningful changes.

• Use clear commit messages.

• VS Code can make staging, committing and reviewing changes easier.

• Do not commit large data, credentials or unnecessary temporary files.

• Your public project repository should support reproducibility, not just file storage.

What to do next¶

After this page:

• use Notebooks and scripts to decide which files belong in notebooks and which belong in scripts,

• use Workflow design to connect repository structure to your analytical steps,

• use Repository to prepare the assessed repository,

• use Reproducibility to check whether someone else can rerun your workflow.