Documentation about Git

I describe here how I use git to support my software project development. This might be useful to other people who have similar requirements.

Important Configuration

E.g. global settings: (there seem to be per project settings too):

$ git config --global xyz
$ git config --global "Your Name Comes Here"
$ git config --global
$ git config --global core.editor notepad

Regards the latter setting for the editor, I would prefer to use EMACS/emacsclient/emacsclientw for commit messages, but that does not seem to be easy to set up. The main issue is that git must know when editing is finished. So when is emacsclient finished?

You can check your configuration with

$ git config --list

To exclude binary files, use .gitattributes so that git does not touch them. To include empty directories put a .gitignore dummy file in there.

For details how to ignore files see

Basic Git Usage

$ git init

creates a new git repository from the current directory.

$ git add <dir>

adds all files in dir.

$ git add -A


$ git add --all

adds all files and directories recursively of a project to staging, irrespective of which branch/subdirectory this command was issued from, whereas

$ git add .

adds all files and directories to staging, but only from the directory downward from where this command was issued.

Committing what is staged:

$ git commit -m "A message about this version"

Committing everything, without explicitely staging first i.e. staging everything:

$ git commit -a -m "A message about this version"

If you omit -m, the editor specified in the EDITOR environment variable will be fired up for the commit message. Alternatively, there is the git config variable core.editor for that (see above). The editor will create a temporary file COMMIT_EDITMSG in the same directory. A default edit message template will be loaded in the editor with a blank first line and some explaining lines with a "#" in the first column. You add the commit message to the first line and add subsequent lines if needed. The lines starting with "#" do not make it in the commit message.

Show changes to a file since the last commit

$ git diff --ignore-cr-at-ol <file>

The option --ignore-cr-at-ol helps to deal with Unix, DOS end of line differences. Obviously, git cares and does not treat files just as binary objects.

Showing the commit history:

$ git log

The seven rules of a great Git commit message

Below seven rules I copied from

Further reading

Git tutorial:

Introduction (de language):

Important commands:

MS Azure git documentation

Install git on WSL. In a Bash prompt:

$ sudo apt install git

Location of config files:

Line ending issues:

A quote from about using source code management for CAD/Kicad files:

"You probably don't want to hear this (most people don't), but git easily does this for you. (Note that I'm talking about git, not Github.)

First: in your kicad project directory, just do

$ git init

This creates a repository that stores all your project versions.

Second: add the project files you want to keep track of. For kicad, there's really only three you need:

$ git add myproj.sch myproj.kicad_pcb

Third: store the current state of your project:

$ git commit -a -m "Some message about this version"

That is all you need to do to setup versioning. Then whenever you have a version you want to save, run the command

$ git commit -a -m "A message about this version"

If you also want to give the snapshot an easy-to-remember name, you can use the command

$ git tag my_version_tag

Then if you ever want to return to that version, use the command

$ git checkout my_version_tag

And if you want to see the history of your project, use

$ git log

I've seen plenty of tools that provide some form of 'archiving'. They're pitiful when compared to using any modern versioning tool like git or Mercurial. If the tool builders were smart, they'd just provide a button you could press to execute the commands I showed above."

Sub-projects, subtrees, submodules

A subproject is a generic term for one of three types of nesting:

Linux kernel example:

How to include a Windows compare tool:

Last change: 2024-01-08
© 2002-2023 Dr. Thomas Redelberger

Close menu