a guide on using git

if you want to learn what git is or about how to use git with a graphical application, this is not the guide for you. in here is a guide on how to use the git cli. also this guide assumes, that you already have git installed.

setting up git

before actually using git, there are some things to be done. you only need to do these things once on a computer, since they will be stored throughout different git versions and projects.

first you need to setup your identity. if you want to change something, git needs to know who wanted to change this. this is why you need to setup do this.

git config --global user.name "dystiv"
git config --global user.email "ivanjoelpollak@proton.me"

this information will be stored outside of any project because different projects will need the same information. to find where this information is stored run:

git config --list --show-origin

if you want to change this for a specific project (you most likely don't ever want this), you can pass in another name and email without the --global option.

one last thing, you might want to change is the default branch name. for a long time, the default branch name was master, however this was considered offensive because it has been associated with slavery. git wnats to be inclusive and thus you can change this. most modern repositories use main instead of master.

to change this enter:

git config --global init.defaultBranch main

getting help

another very useful thing is to know how to get help. if you're offline and don't have the internet, you will need this.

to read more about git, you can use it's manpage:

man git

this will however not describe the usage of, for example, git config.

generally you can read the manpages for the sub-apps using this scheme:

man git-<verb>

so for example:

man git-config

git basics

you typically get an existing repository or create a repository from a folder on your local machine.

creating a repository

if you have an awsome project and you want to create a repository out of this, you will need to go into this folder and using the following command:

git init

at this point git wont track any files yet. you should start by adding some files and creating an initial commit:

git add *.c # add all files with the .c extension
git add LICENSE
git commit -m "initial commit"

cloning a repository

to get a remote repository use the following command. this will clone the repository into your working directory.

git clone https://git.sr.ht/~dystiv/foochr

track changes

to check the current status of the project, you can use the git status command:

dystiv@dystivs-MacBook-Pro website % git status
On branch main
Your branch is up to date with 'origin/main'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        blog/a_guide_on_using_git.md

nothing added to commit but untracked files present (use "git add" to track)

here you can see, that i am up to date with my remote repository. you can see this because it tells me: Your branch is up to date with 'origin/main'.

however it also tells me, that i currently have untracked files. in my case, i have a file called a_guide_on_using_git.md in the blog directory. git also tells me that i can use git add to add my file.

i can now add my file and run git status again:

dystiv@dystivs-MacBook-Pro website % git add blog/a_guide_on_using_git.md
dystiv@dystivs-MacBook-Pro website % git status
On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        new file:   blog/a_guide_on_using_git.md

here git tells me that i can unstage my newly added file if i want to.

if i modify my file after i added it, it will only commit the changes made before adding it. to also include the newly made changes, i will need to add it again.

ignoring files

if you have a file you don't want git to track at any time, you can create a .gitignore file. lets say, you have an app and you only want to track the source code and not the binaries that you compiled. if you now want to exclude the binary, just create and open the .gitignore file and write down the name of your file:

echo "myapp">.gitignore
cat .gitignore

git diff

if git status is too vague for you, you can use git diff. this is useful if you want to know exactly what you changed and not just what files have changed. note that by default, only changes that are not yet staged will be shown:

dystiv@dystivs-MacBook-Pro website % git diff
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8ebb991..643e24f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -65,7 +65,8 @@ branch directly, things can get messy.
 Please include a nice description of your changes when you submit your PR;
 if we have to read the whole diff to figure out why you're contributing
 in the first place, you're less likely to get feedback and have your change
-merged in.
+merged in. Also, split your changes into comprehensive chunks if your patch is
+longer than a dozen lines.

 If you are starting to work on a particular area, feel free to submit a PR
 that highlights your work in progress (and note in the PR title that it's

if you also want to see the changes that have been staged already, you will need to use:

dystiv@dystivs-MacBook-Pro website % git diff --staged
diff --git a/README b/README
new file mode 100644
index 0000000..03902a1
--- /dev/null
+++ b/README
@@ -0,0 +1 @@
+My Project

commiting your changes

if you now want to commit your changes, you can use the git commit command. this will open your text editor of choice, where you can write in your commit message. by default there are some comments, explaining how to use this. if you don't want to use a seperate editor for writing this short message, you can add the -m flag:

dystiv@dystivs-MacBook-Pro website % git commit -m "Story 182: fix benchmarks for speed"
[master 463dc4f] Story 182: fix benchmarks for speed
 2 files changed, 2 insertions(+)
 create mode 100644 README

if you want to, you can also skip the staging stuff using the -a flag. this will automatically stage every file that is already tracked before the commit:

dystiv@dystivs-MacBook-Pro website % git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

    modified:   CONTRIBUTING.md

no changes added to commit (use "git add" and/or "git commit -a")
dystiv@dystivs-MacBook-Pro website % git commit -a -m 'Add new benchmarks'
[master 83e38c7] Add new benchmarks
 1 file changed, 5 insertions(+), 0 deletions(-)

removing a file

if you want to remove a file from the project, you first need to delete it on your file system and then also delete it from git. git will try to track it still, if this is not done. also the remote repository will still include this file even it's deleted on your system. to avoid this use:

rm somefile.md
git rm somefile.md

moving a file

git will automatically detect the movement of files. however you can use git mv <old-file> <new-file> if you really want to. this however will be equivalent to:

mv <old-file> <new-file>
git rm <old-file>
git add <new-file>

the only difference is that you don't need to type in three commands but only one.

viewing the commit history

to view the git history, you can use git log. by default, newest commits are on top. if you want to also see the changes made (the patch output), you can add the -p flag: git log -p.

remotes

remote repositories are versions of your project that are hosted on the internet or on the network somewhere. this repositories allow for better collaboration with other developers. a common remote repository hosting service is github or in my case sourcehut.

to show the remotes of your current repository use the following:

dystiv@dystivs-MacBook-Pro website % git remote
origin

to have a more verbose output use the -v flag:

dystiv@dystivs-MacBook-Pro website % git remote -v
origin  git@git.sr.ht:~dystiv/website (fetch)
origin  git@git.sr.ht:~dystiv/website (push)

you can also have more than one remote. in this case, all of those will get listed:

$ cd grit
$ git remote -v
bakkdoor  https://github.com/bakkdoor/grit (fetch)
bakkdoor  https://github.com/bakkdoor/grit (push)
cho45     https://github.com/cho45/grit (fetch)
cho45     https://github.com/cho45/grit (push)
defunkt   https://github.com/defunkt/grit (fetch)
defunkt   https://github.com/defunkt/grit (push)
koke      git://github.com/koke/grit.git (fetch)
koke      git://github.com/koke/grit.git (push)
origin    git@github.com:mojombo/grit.git (fetch)
origin    git@github.com:mojombo/grit.git (push)

adding remotes

to add a remote repository use the following scheme: git remote add <shortname> <url>. for example:

$ git remote
origin
$ git remote add pb https://github.com/paulboone/ticgit
$ git remote -v
origin	https://github.com/schacon/ticgit (fetch)
origin	https://github.com/schacon/ticgit (push)
pb	https://github.com/paulboone/ticgit (fetch)
pb	https://github.com/paulboone/ticgit (push)

to now fetch the changes made on the pb remote use:

$ git fetch pb
remote: Counting objects: 43, done.
remote: Compressing objects: 100% (36/36), done.
remote: Total 43 (delta 10), reused 31 (delta 5)
Unpacking objects: 100% (43/43), done.
From https://github.com/paulboone/ticgit
 * [new branch]      master     -> pb/master
 * [new branch]      ticgit     -> pb/ticgit

pushing to remotes

to push your changes to an origin use:

git push <remote> <branch>

you now can inspect the origin:

dystiv@dystivs-MacBook-Pro hbos-ui % git remote show origin
* remote origin
  Fetch URL: https://github.com/dystiv/hbos-ui
  Push  URL: https://github.com/dystiv/hbos-ui
  HEAD branch: dev
  Remote branches:
    dev                                         tracked
    feature/crossover-design-backend-connection tracked
  Local branch configured for 'git pull':
    dev merges with remote dev
  Local ref configured for 'git push':
    dev pushes to dev (up to date)
dystiv@dystivs-MacBook-Pro hbos-ui %

removing and renaming remotes

to remove an origin use:

dystiv@dystivs-MacBook-Pro hbos-ui % git remote
origin
dystiv@dystivs-MacBook-Pro hbos-ui % git remote remove origin
dystiv@dystivs-MacBook-Pro hbos-ui % git remote

also you can rename a remote:

dystiv@dystivs-MacBook-Pro hbos-ui % git remote
origin
dystiv@dystivs-MacBook-Pro hbos-ui % git remote rename origin github
dystiv@dystivs-MacBook-Pro hbos-ui % git remote
github

git tagging

you can tag specific points in a repository's history as being important. common usages might be release points like v1.0, v1.1, etc. to list the existing tag's, use:

$ git tag
v1.0
v1.1

creating tags

in git there are two types of tags. the lightweight tag is, as the name implies, a very lightweight tag. it doesnt contain much information. you cannot comment your tag or any other things. you can just provide a tag name.

the annotated tag is the big brother of the lightweight tag. in here, you can add a message, sign it with GPG (GNU Privacy Guard) and they are checksummed. this means that they contain the tagger name, email and date.

to create a lightweight tag use:

$ git tag v1.0
$ git tag
v1.0

to create a annotated tag use:

$ git tag -a v1.0 -m "version 1.0 release!!"
$ git tag
v1.0
$ git show v1.0
tag v1.0
Tagger: dystiv <ivanjoelpollak@proton.me>
Date:   Sat May 3 20:19:12 2025 -0700

version 1.0 release!!

commit ca82a6dff817ec66f44342007202690a93763949
Author: dystiv <ivanjoelpollak@proton.me>
Date:   Mon Mar 17 21:52:11 2025 -0700

    Change version number

sharing tags

by default git push doesn't transfer tags to remote servers. to push them, you explicitly need to tell git to push them. to push them use:

$ git push origin v1.0

if you have multiple tags and want to push all of them at once, use:

$ git push origin --tags