Using Git for the first time

Setting global parameters

First things first, set the configuration for username and email so that the future comments on the code edits show who edited the code:

git config --global user.email "[e-mail]"
git config --global user.name  "Your Name"

Initializing a directory (folder) with git

Go into the folder of your project and type:

git init .
git add .
git add .gitignore
git commit -m "comments about the commit"
# optional (if working with github.com):
git push origin

Initialization. The git init . command creates a new folder in your directory (folder) called .git . This folder is where all the information regarding the git system is stored, so never delete it.

Staging area. The git add . adds all the files in the current folder (. means all the file in the folder in Bash) into the "Git system" so that Git tracks the files and their changes. If you need to add a specific file you can use the name of the file instead of . and type (if your file's name is file_to_add.txt):

git add file_to_add.txt

The command git add .gitignore adds a specific file, called gitignore that will contain the names of files or the extensions of files that you don't want the "git system" to track. If you have data files (especially large ones), for example csvfiles, you can create a gitignore file with the line*.csv in it. Examples of gitignore files are given in the Appendix (see also below On .gitignore and excluding files)

Note that with the git add command, we have not yet recorded the new files. We only staged them.

Commit. To finalize the recording, we need to use the commit command. The -m in git commit -m command indicates that what follows is a comment on the commit. You can see the commit message as the title of your commit, so it must be relatively short and descriptive, but not too vague either.

The rule is to use a comment that would follow this expression: "this commit will ...". So verbs must be in the infinitive form. For example, a commit comment could be "add a parameter to the optimization function".

Finally, the last instruction, git push origin , is used to "push" the new state of the files to a remote repository (for example on Github.com). If working only locally, this command is not used.

Later commits

The repository must only be initialized once. Later on, when files are edited and saved, the commands to run to "take snapshots" of the files, are:

git add edited_file.txt
git commit -m "commit comment"
# optional (if using Github.com):
git push origin

[Optional] If working with Github.com, you should fetch all the changes (from colleagues) from Github.com into your local directory before making new changes, using

git fetch --all

You can also use --prune in order to drop any unused branches

git fetch --all --prune

Advanced commits

If you have already "commited" files but want to add new changes to the past commit, you can also "append a commit" to the last commit using

git commit --amend --no-edit

or, if you'd like to also edit the commit message:

git commit --amend -m "change commit message"

[Optional: if using Github.com] Following a commit --amend, the push needs to be "forced" with -f, which is usually a bad thing (but in this case it is ok) because it rewrites history.

git push -f origin

To tag a commit, use

git tag -a v1.0 -m "testing version"

On .gitignore and excluding files

.gitignore. The file .gitignore contains information on files or folders that one doesn't want to be part of Git (Git will ignore these files and not keep a record of their changes).

The .gitignore file is convenient when some of the files inside the folders are not to be shared (for example a note to yourself, or some data file that can be downloaded through your code).

The file must be called .gitignore. Notice that the name starts with a dot. Windows sometimes doesn't like that. If so you can just copy a .gitignore file from a public repo or one can instead create the file .gitignore. with the dot at the end. It should work.

The .gitignore file must be at the root of the repository, at the same level as the .git folder

Making global configuration ~/.gitignore_global and running git config --global core.excludesfile ~/.gitignore_global to add this to your git config.

Global .gitignore. The file ~/.gitignore_global is intended to be a global .gitignore file. This means it will contain rules for ignoring files that you don't want Git to track across all your Git repositories on your system. For example, you might want to ignore all .log files or editor-specific temporary files like .vscode. You create this file in your home directory (denoted by ~). Once this file is created run

git config --global core.excludesfile ~/.gitignore_global

The command git config --global core.excludesfile ~/.gitignore_global is used to tell Git where to find your global .gitignore file. When you run this command, it adds an entry to your global Git configuration (which is stored in ~/.gitconfig) specifying the path to the global ignore file. The --global flag means this configuration will apply to all repositories you work with on your system.

.git/info/exclude. The git/info repo contains repository-specific configurations. The file .git/info/exclude contains file patterns or directories that Git will ignore (within that specific repository). The rules you add to this file .git/info/exclude are local to your clone of the repository. This means they only apply to your copy of the repository and do not affect other clones of the repository. Unlike the .gitignore file, which is usually tracked and shared among all users of the repository, the exclude file is not committed to the repository. Therefore, changes to this file will not be seen or used by other users who have cloned the repository. This feature is useful for ignoring files that are specific to your environment or workflow, which might not be relevant to other users working on the same project.

Mistakes

Undo mistakes

restore. If you staged a file (using git add <filename>), you can unstage it by typing

git restore --staged <filename>

It is the opposite of git add. It does not affect the file itself. It removes it from the list of files to be committed.

It is equivalent to the following (in older git versions)

git reset HEAD --staged <filename>

The HEAD here refers to the current state of the last commit, effectively saying "reset the staging area for this file to the state it was in at the last commit."

To reset the file as in the last commit (this will undo the change in the files, so use carefully), run

git restore -- <filename>

To undo the commit (but keep the files as they are), run

git reset --soft HEAD~1

revert. To undo all the changes made on a given commit, you can use revert. It will create a new commit that undo the changes of the commit mentioned:

git revert <commit-hash>

For example: git revert 1a2b3c4d . To know the hash of the commit, use git log (see below).

It is safe to use because it doesn't edit history, jsut create a new commit, so you can always go back to where you were.

Log

git log --oneline --graph --all --decorate

Some other useful log commands

git reflog
git log --grep="term to find in commits"
git log -- <name of file> --stat

Advanced

Abord an ongoing merge (that is not going well)

git merge --abort