Simplest version of using git from the command line - the basics to get started

GitBasics.md

Disclaimer: There are many subtleties to using git - this is a very basic workflow. Discuss in your team how you want to work!

Pre-req

This gist assumes that you have authorisation to clone/pull/push from your repo. Either it is public, or you have set up ssh authentication.

Git basics

git clone <http or ssh link from git portal>
# change into the folder that is created as a result of the cloning.
cd <repo name>

Standard workflow

step 0 - update your local copy of the repo

⚠️ skip this only if only just cloned, otherwise always start by ensuring your local is up to date

# change into the repo
cd <repo>
# check what remote the local repo is linked to
git remote -v
# check which branch you're on:
git branch
# update the branch
git pull
# [if relevant] repeat this for any other branch that needs updating
git checkout other_branch
git pull

step 1,2,3:

# make changes within the repo. Then: 
git status         # see what new changes have been made
git add .          # this stages any file (.) in the current directory
                   # *** ensure you are in the root of the repo when you do this! ***
                   # You can keep running git add to add more things to a commit before 
git status         # see what's ready to be batched up into a commit. 
git commit -m "my commit message for the work I've just done" 
                   # do this often
git status         # see whether you have commits you've not yet pushed. Until you do, they are not safely backed up to your cloud repo.
git push           # the first time, git will tell you to configure the branch in the online version of the repo
                   # - just follow instructions: git push --set-upstream <branchname>

[OPTIONAL] Create a working branch for yourself before making changes

Note: if it is your own repo and you're not collaborating, you can work directly in main as per the above. Otherwise, agree a branching strategy with your collaborators. This might be a convention like 'branches will be named by person, e.g. dev-myinitials' or 'we'll create a new branch for every feature we add to our app, named e.g. feat/fileupload'. In open-source repos, this is often documented in a Contributing.md file in the root of the repo.

git checkout -b mybranch

-> this creates a branch as an exact copy of the branch you were on before. For now, this only exists locally on your machine.

Check this with:

git branch

-> this should put a star next to the branch you are in.

Note: Always make sure that you add/commit your own changes (see standard workflow above) before you attempt to switch branches.

How to get your changes from a branch into main

Use the pull request feature in the github UI once you've pushed to your own branch.

Note: it is best to first get your own working branch fully up to date with what has been happening on main in the meantime (see next). That way, you deal with any merge conflicts first, rather than the person who reviews your pull request later.

How to get any main branch changes into your working branch

Do this only once you've committed changes to your working branch with the Standard workflow above - check that you're all clear:

git status
-> "nothing to commit, working tree clean"

Then, switch to the main branch

git checkout main    # this switches to your local copy of the main branch (it won't yet know what has happened online)
git pull             # you now have all the latest changes from others in your local copy

see "Dealing with merge conflicts" if you hit any.

Switch back to your working branch and merge main into it

git checkout mybranch
git merge main -m "my note about the fact that I'm updating my branch with main"

(optional) push your updated branch to the online repo

git push

or carry on making local changes with the standard workflow above.

See also

Dealing with merge conflicts