Your First Commit

You have set up your environment, installed your packages, and written your first notebook. Before moving to any science, save this work permanently with Git. This habit — committing at every meaningful checkpoint — is one of the most valuable practices you can build as a computational scientist.

Connecting your project to GitHub¶

First, create a new repository on GitHub:

1. Navigate to github.com and login to your account
2. Click the + icon (top right) → New repository
3. Name it saxs-tutorial
4. Add a short description if you like
5. Choose Public or Private
6. Check Add a README file
7. Check Add a .gitignore and select Python
8. Click Create repository

Now link your local saxs-tutorial folder to the repository on GitHub. Open a terminal inside VS Code by pressing Ctrl+` (or going to Terminal → New Terminal), then run:

$ git init
$ git remote add origin git@github.com:yourusername/saxs-tutorial.git
$ git branch -M main

Replace yourusername with your actual GitHub username. You can find the exact command on your new repository's page on GitHub — look for the section titled …or push an existing repository from the command line.

Staging, committing, and pushing¶

Step 1: Check what Git can see.

$ git status

Git lists new or modified files that have not yet been committed. Your notebook and pyproject.toml should appear here.

Step 2: Stage the files you want to include.

$ git add chapter_01_hello.ipynb pyproject.toml README.md

Staging is a deliberate step — it lets you choose exactly which changes go into this commit. You do not have to include every modified file every time.

Step 3: Commit with a clear message.

$ git commit -m "add hello world notebook and project configuration"

Step 4: Push to GitHub.

$ git push -u origin main

The -u origin main flags only need to be included on the first push. After that, git push alone is sufficient.

Navigate to your repository on GitHub and refresh the page — your files should be visible there.

Files that should not be tracked¶

Some files should never be committed to Git. The .venv folder can be several hundred megabytes and can always be recreated from pyproject.toml using uv sync. The .ipynb_checkpoints folder that Jupyter creates automatically is also unnecessary.

If you did not use GitHub's Python template when creating your repository, create a file called .gitignore in your project root and add the following:

.venv/
__pycache__/
*.pyc
.DS_Store
.ipynb_checkpoints/

Then add and commit it:

$ git add .gitignore
$ git commit -m "add gitignore for Python project"
$ git push

How often should you commit?¶

There is no single correct answer. A useful rule of thumb: commit whenever you reach a state you would be unhappy to lose. In practice this means after writing a new function, after a plot looks the way you want it, or at the end of each working session.

Smaller, more frequent commits with descriptive messages are almost always better than large, infrequent commits labeled stuff or final2.

$ git add chapter_01_hello.ipynb
$ git commit -m "add description of sine wave plot to notebook"
$ git push

You now have a fully configured scientific computing environment and a version-tracked project on GitHub. Everything you build from here will be saved and recoverable.

What's next: Section 2 → — building a mathematical model of X-ray scattering from a sphere.