Git and GitHub for one person

I started my first project with an assistant in January, and I chose GitHub to host it because I knew little about hosting. I am a chemical engineer and I had never used Git. For the next several months I used it without understanding what it was doing.

Git and GitHub are two different things

Git is a program on my computer that keeps the history of a folder. GitHub is a website that stores a copy of that history.

In February I installed VS Code, signed in to GitHub and cloned my repository, which means downloading a copy of it to my computer. The “Git: Clone” command did not show in VS Code at first, then it appeared. The repository was empty because I had deleted everything in it earlier. I built it again on my computer, looked at it there, and did not push it back up, because there was no point publishing it as it was.

A commit

The unit of history in Git is the commit. The Pro Git book describes it as a picture of what all the files look like at that moment, and Git keeps a series of those pictures.11Pro Git, chapter 1.3: snapshots and not differences; the three states modified, staged and committed. A file goes through three states on the way: modified, staged (marked to go into the next snapshot) and committed.11Pro Git, chapter 1.3: snapshots and not differences; the three states modified, staged and committed.

git add .
git commit -m "a short message saying what changed"

The nearest thing I know from my own trade is an issued revision of a drawing. You can mark up the working copy all day, but Rev B exists only when it is issued, with a date and a name on it, and you can always go back to it. Git also wants the name, so before the first commit you set your name and email once.

My first real one was an analysis of public workforce statistics that I did in a notebook. The first commit had 27 files and 2,718 insertions. The README came after that, because I first created it one folder up by accident.

The part I did not understand was that a folder with Git in it has no history unless I make the commits. About a week later I was building something else with an assistant, file by file, and one evening a setup script gave me back much less than we had built. So I checked:

git log

The repository held two early commits and nothing of the work since, because I had never committed it. In March I opened that old folder again and there was nothing in it to dig for, so I started over from a fresh template.

A branch

A branch is a movable pointer to one of the commits. Making one copies nothing, and new commits on it leave the main line where it was.22Pro Git, chapter 3.1: a branch as a lightweight movable pointer to a commit; creating a branch creates a new pointer.

Working alone I have used it for one purpose, which is a trial I might throw away. When I was checking whether a tool could do what I wanted before I built on it, the test went on its own branch, and its commit had 17 files. If the trial had failed I could have deleted the branch, and the main line would have stayed as it was.

Push

A commit lives only on the computer where it was made. A remote is a copy of the project hosted somewhere else, and git push sends the local commits to it.33Pro Git, chapter 2.5: remote repositories, git push <remote> <branch>, and the name origin. After you clone from GitHub, Git calls that server origin.33Pro Git, chapter 2.5: remote repositories, git push <remote> <branch>, and the name origin.

git push origin main

So committing and pushing are two decisions. The day I cloned for the first time I did not push, because what I had was not good enough to publish. The analysis I did push, and that first push was 4.02 MiB.

.gitignore

A .gitignore is a text file that lists what Git should leave alone.44gitignore documentation: the file specifies intentionally untracked files; files already tracked are not affected. I put in it what can be rebuilt, like a Python virtual environment or the node_modules folder, and what must not be published, like files with keys in them.

It has to be there before the first commit, because a rule added later does not affect files Git is already tracking.44gitignore documentation: the file specifies intentionally untracked files; files already tracked are not affected. In my analysis repository it went in with the first commit. Months later a coding agent set up a new repository for me and its second commit was the .gitignore: an internal data folder, node_modules, the build folders and the environment files. Then it tested the rule with git check-ignore on a dummy file under the data folder, before any real data went in.

I think you also have to remember that an ignored file is in no commit, so pushing does not back it up. That data needs its own copy somewhere.

Using it alone

GitHub defines a private repository as one that only the owner and the people the owner shares it with can reach.55GitHub Docs, “About repositories”: a private repository is accessible only to the owner and people explicitly given access. With nobody else on the project I still get two things from it.

One is a copy off the machine. In February I moved a modeling project to a new computer by copying the folder, and the same project also existed as a folder ending in v2 and another ending in v3, with files copied between them. The other is the dated record. git log tells me what the work looked like on a given day, which I would otherwise answer from memory and file timestamps.

In August Git and committing felt like too much for me, so for one job I chose a host where I could upload the files myself. Four days later I moved to a coding agent, and the first thing it did was work in a repository. The repository was empty, so its first commit was the rules file and its second was the .gitignore. The first commit came out with the agent as the author, and my rule is that commits carry my name, so it reset the author. The fix that lasts is to set the name once for the whole machine, because a fix inside the agent’s container does not persist:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Footnotes

1. Pro Git, chapter 1.3: snapshots and not differences; the three states modified, staged and committed. ↩ ↩²

2. Pro Git, chapter 3.1: a branch as a lightweight movable pointer to a commit; creating a branch creates a new pointer. ↩

3. Pro Git, chapter 2.5: remote repositories, git push <remote> <branch>, and the name origin. ↩ ↩²

4. gitignore documentation: the file specifies intentionally untracked files; files already tracked are not affected. ↩ ↩²

5. GitHub Docs, “About repositories”: a private repository is accessible only to the owner and people explicitly given access. ↩