# Repository
:::{admonition} My lies are exposed
:class: warning
I'll come clean: On the previous couple of pages, I
presented the commands as if I was using git solely
as a way of tracking my own files in my own project.
You can use git in this way.[^tutorial] But that's not the way you're
going to use it when you work with a scientific research group.
The truth is that you're going to use git with a repository of some sort:
- It may be that your files will be fairly independent with respect to
others in your working group. In that case, you'll probably be
asked, at the end of the summer, to upload your files to a central
git repository so that others can access what you've done.
- It's more likely that you'll be asked to work with files that
someone else has written. You'll copy the files to your own area,
and perhaps create one or more branches for your work. At some
point, after testing and review, you might be asked to merge your
work back into the original project.
:::
[^tutorial]: In fact, that's how I use git to manage the files
used to generate the web pages for this tutorial. As of 2025,
I've not chosen to put the "source" code of these pages
(what you see if you click "View page source" in the upper
right) onto a central repository.
The idea behind a git "repository" is that, in addition to maintaining
the files in your own directory, there is some remote location (a
different directory, a different computer, a different site) that also
maintains a copy of the files.
When you're working with git, files are only committed when you issue
a command (`git commit`). When you're working with a repository, it
only receives an updated version of your committed files when you
issue a specific command (normally `git push`, which I'll discuss
below).
Where will this remote location / repository be? It's not hard to set
up a git repository on any system.[^proof]
[^proof]: As proof of that statement, I've done it!
It's more common these days to use a system that provides additional
services above what what "vanilla" git offers. For the projects that
I've worked on in physics, that system has been
[GitHub](https://github.com/).[^mixed]
[^mixed]: _Editorial_: My feelings on GitHub are decidedly mixed. On
the one hand, GitHub is a free and convenient organizational tool
for the kinds of projects that we see in the sciences. On the
other hand, GitHub is owned by Microsoft, which almost certainly
uses its content to train LLMs (remember my {ref}`rant about LLMs
`?).
I've "shopped around" for a different well-known public repository
service. As of 2025, I see [Sourceforge](https://sourceforge.net/)
and [Gitlab](https://about.gitlab.com/) as viable
alternatives. However, any of these source-code hosting services
are going to have some issue in my eyes, since they need to have
some kind of revenue stream; that requirement doesn't always agree
with the development of scientific projects.
As a practical matter, your working group will tell you which remote
repository location to use. For the sake of simplicity, I'm going to
assume that's GitHub. For other services, your working group will
provide directions.
## Setup
The initial steps are:
- [Set up a GitHub account](https://github.com/signup).
- [Set up
git](https://docs.github.com/en/get-started/git-basics/set-up-git). Note
that git is already installed on every system of the Nevis particle-physics Linux cluster.
- I find it's easier to set up [GitHub connections via
SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).[^reason]
[^reason]: The reason why is that I already use tools like
[ssh-keygen](https://www.baeldung.com/linux/generating-keys-without-passphrase)
to organize SSH keys between the computer systems I
manage (and I encourage you to use it with your laptop-to-Nevis
ssh connections). Adding my public SSH key to GitHub was trivial
for me, since I already had a private key.
## Creating a new repository
Let's assume that you've got your files in a directory. You've used
[git init](https://git-scm.com/docs/git-init) to set up git to manage
the files in that directory.[^init]
[^init]: It's not a bad practice to do this in an empty directory,
then use [git add](https://git-scm.com/docs/git-add) to include
files to manage as you work on them. Some guides suggest using a
command like
git add .
This adds every file in your current directory to the list managed
by git. However, I suggest _not_ doing this.
The reason is that most of us create work files, intermediate edit
files, and other miscellania that we don't want to include in a
formal project release. I think it's better to add the specific
files to track than to simply "add everything and sort it out
later."
You will want to [define the remote repository using GitHub's web
interface](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository).
The next step is to tell git that [there'a remote repository
associated with the contents of your local directory](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository):
git remote add origin https://github.com/OWNER/REPOSITORY.git
Note that the name `origin` is can be any alias. However, the name
`origin` is standard and I suggest that you don't change it.
To send the current git "state" (up to your most recent `git commit`)
to the remote repository, use [git
push](https://git-scm.com/docs/git-push):
git push origin main
Note that this assumes that you used a couple of defaults:
- `origin` for the alias for the remote repository;
- `main` for the default branch name.
## Downloading an existing repository
As I noted above, this is the more likely case: Your working group has
an established repository of files. They want you to copy this to your
own area to work on it.
They'll probably provide you with the necessary commands to do
this. In case they haven't, here are some generic instructions:
- [Clone](https://git-scm.com/docs/git-clone) the repository from
GitHub. Assuming that you've set up an SSH key as I recommended
above, the command will be something like:
git clone git@github.com:OWNER/REPOSITORY.git
This will create a directory in your area whose name is "REPOSITORY".
You do _not_ create that directory in advance; `git clone` will
create it for you.
Note that the text `OWNER` and `REPOSITORY` in the above command are
examples. Your working group has to tell you the GitHub name of the
owner of the repository, and the name of the repository.
- Go into that directory. Assuming that the directory has the naive name of `REPOSITORY`:
cd REPOSITORY
- Bring the contents of that directory up-to-date with the remote repository, include
all branches and tags:
git fetch
:::{figure-md} repository-fig
:align: center
Here's a sketch of what a physics software development
environment might look like. A group of physicists are all working from
the same code base. Perhaps they're each creating their own branches
as they work on their areas of expertise. At some point they'll
coordinate with each other (larger experiments have a software manager) to
merge their work into the code in the central repository.
:::
## More fun with branches
Why would you want to use `git fetch` to synchronize all the branches
from the remote repository?
Many groups want you to make changes in a separate branch from the
main one. A common name for this branch is `develop`, but your working
group may have a different standard.
To switch to working with a branch named `develop`:
git checkout develop
You can simply work (and `git commit`) changes within that branch. You
can even {ref}`create ` your own branch-within-a-branch if that turns out to
be practical for your work:
```
git commit -a -m "Save any commits I've made to the 'develop' branch"
git branch my_own_work
git checkout my_own_work
# Do whatever it is you'd like to do.
git commit -a -m "Commit the changes I made to 'my_own_work'"
# When it's ready and your working group approves:
git checkout develop
git merge my_own_work
```
If you're going to push your work to the repository, make sure you're
pushing it to the correct remote branch; e.g.,
git push origin develop
:::{figure-md} git_commit-fig
:align: center
by Randall Munroe
:::