Elara Research Docs

Git quick reference

9 min read

At Project Elara, we use the open-source version-control system Git for tracking contributions. Effectively, Git acts as a “time machine” for Project Elara, saving “snapshots” of each of our repositories in time, which we can always go back to later. Git can be pretty complex, so here is a list of useful Git commands to use.

Note: Eventually, this will be added to the Elara Handbook (after making this more comprehensive and with further revision).

General concepts

  • A repository is any folder that is tracked by Git. Repositories can be local (on your own computer) or remote (online)
    • Another word used for remote is upstream, which comes from the river analogy of a repository - your local repository are located “downstream” from the remote (online) repository, while the remote is “upstream” from your repository
  • A commit is a saved change in the repository’s history. Modifying some files, creating new files, or deleting files all qualify as changes.
  • A branch is a self-contained version of the repository. A repository can have multiple branches (like branches of a tree) which each contain code/docs/etc. developed in parallel. This is one of the most useful features of Git!
  • A merge is when you combine two branches together. This allows the changes from one branch to be added to those in another branch.
  • A pull request is a request for a merge. It is frequently used when you want your changes to be reviewed before merging.
  • A push is an upload of your local changes to a remote (online) repository. It is only important for repositories that are synchronized with a remote repository.
  • Similarly, a pull is a download of changes from a remote repository to your local repository. Again, it is only important for repositories that are synchronized with a remote repository.

Typical Git workflow

Note: explanations of each of these commands is given below.

# download online repository
git clone https://your-repository-url.com
cd your-repository
 
# make some cool changes...
 
git add <your-changed-files>
# if you are lazy you can instead run:
git add * # this adds all your changes
 
git commit -m "Description of your changes" # 7 words or less
git pull --no-ff # sync online changes
git status # check everything looks good
git push # upload your changes

Basic commands

  • git init: This command sets up git to “upgrade” a normal folder into a git repository
  • git clone: This command downloads a remote repository onto your computer.
  • git status: This command shows the current status of your repository. It is recommended to run this command often and before you run any other Git command since it might help you troubleshoot issues or find issues prior to running a (potentially destructive) command.
  • git add path/to/files/or/folders: This command adds files (or non-empty folders) you have modified/created/deleted. You must run this command before you commit anything!
  • git rm path/to/files/or/folders: This command deletes files (or non-empty folders) from your repository. It is highly recommended to use this command as opposed to deleting the files from your file manager manually or using the rm command directly, since git rm allows Git to track the change in a more consistent way.
  • git commit: This command creates a commit, and opens a default text/code editor to create a commit message with a description (assuming you have run git add beforehand)
    • Important: In the commit message, a short (<7 word) description should be in the first line, the second line should be blank, and a long description should be put in the third line and any following line(s). There is no line limit, but try to keep commit messages wrapped to <15 words per line.
    • Unless you are already experienced with the Linux/Unix commandline, it is not recommended to use this command out of the box since the default editor chosen by git is Vim, which uses nonstandard key-bindings.
    • To alleviate this issue, it is recommended to run git config --global core.editor notepad (to use Windows notepad as the text editor) or git config --global core.editor <your-preferred-editor> on Mac/Linux (substitute <your-preferred-editor with the commandline name of the editor you want to use)
  • git commit -m "Your description": This command creates a commit with only a short description, and is recommended for quick changes (or if you are a beginner at Git)
  • git commit -s -m "Your description": Same as git commit -m but it adds a signature to the commit. Generally unnecessary, unless you are working on a repository with very specific licensing terms (we recommend this for public domain-licensed repositories)
  • git commit --amend: Modifies your most recent commit. You must run git add beforehand to track your changed files!
    • The commit message format is the same as git commit (first line for short description, second line blank, third and all following lines for long description)
    • This suffers the same issue as git commit in that it launches Vim by default, so it is not recommended to use it out of the box
    • It can be fixed the same way (using the git config commands to set the default editor to something else)
  • git commit --amend -m "Your revised description": Modifies your most recent commit, with a description. Useful for changing your last commit’s commit message (for instance, if you misspelled a word in it)
  • git commit --amend --no-edit: The same as git commit --amend, but it automatically uses the same commit message as your last commit, so you don’t have to re-type the same commit message over again
  • git pull: downloads (“pulls”) changes from a remote repository to your local repository.
    • There are also specific versions of this command for different purposes.
    • For instance, git pull --ff-only performs a “clean” pull and tries update your repository without touching your local changes. However, it does not always work!
    • Meanwhile, git pull --no-ff performs a merge and tries to combine your repository with the remote repository’s changes, which can be more “messy”, but works more reliably
    • If neither command works, you have something called a conflict. These are infamously annoying to deal with, and they usually come from too many people editing the same files at once. To fix conflicts, consult this guide
  • git push: uploads (“pushes”) changes from your local repository to a synced remote repository.
    • In certain cases, you may want to override the remote repository’s changes with your own. For this, you can run git push -f for a forced push. This is a dangerous action so only do this if you’re sure!
  • git log: Shows a list of all changes by all contributors. Use the k key to scroll up, the j key to scroll down, and the q key to quit
    • A prettier version of this command (though not always more useful) is git log --graph --all --pretty --oneline
  • git blame path/to/file: Shows which contributors have edited a particular file in the repository

Configuration

  • git config --list: This command shows all your Git configuration options. Bear in mind that this can be quite long!
  • git config --global user.name "Your name": This command sets your name, which will be tracked in your commits. You do not have to use your real name if you are uncomfortable (unless if you are taking the RCOS class, in which case you unfortunately do have to)
  • git config --global user.email "your-email@example.com": This command sets your email, which will also be tracked in your commits. If you’re working on a repository synced to a remote repository, be aware that this email will be publicly visible!
    • For Project Elara contributors, this should be the same as your Codeberg account email
  • git config --global init.defaultbranch NAME: This command sets the default git branch name for new repositories. In the past, the default name was “master”, but due to its historical connotations, it is recommended to run git config --global init.defaultbranch main to set the default branch name to “main”

Branches

  • git checkout -b NEW_BRANCH_NAME: This command creates a new branch with the name NEW_BRANCH_NAME (substitute it for your chosen branch name).
  • git checkout ANOTHER_BRANCH_NAME: This command switches to another branch with the name ANOTHER_BRANCH_NAME (substitute it for your chosen branch name).
  • git branch -a: This command lists all branches
  • git branch -m REVISED_BRANCH_NAME: This command renames your current branch to REVISED_BRANCH_NAME (substitute it for your chosen revised branch name)
  • git push --set-upstream origin: This command pushes a newly-created branch to the remote (online) repository.
  • git merge --no-ff OTHER_BRANCH_NAME: This command merges another branch with the name OTHER_BRANCH_NAME (substitute for the branch’s actual name) to the branch you are currently working on.
    • This is not recommended for use in multi-contributor repositories except in special cases; instead, Codeberg and GitHub have tools to make a pull request, which allows others to review the changes before merging.
  • git merge --abort: This command stops a merge; useful if something goes wrong during a merge.

Submodules

  • A submodule is like a git repository inside another git repository. It is very useful when you want to include code from another git repository and sync the code with that repository
  • git submodule update --init --recursive: This command updates all existing submodules. This is important because Git generally does not download submodules by default.
  • git submodule add https://your-submodule-url.git: This command adds a new submodule from the online URL https://your-submodule-url.git (obviously replace it with the actual URL of the repository you are using).
    • You can commit a submodule with git add <submodule-path> to track it in your Git history
  • To delete a submodule, run git rm <submodule-path> and commit the change. Historically this was much more complicated to do; see this Stack Overflow post for historical instructions, but now it should be much simpler.

Other useful resources

Graph View

Backlinks