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 user.name "Your Name Comes Here"
$ git config --global user.email you@yourdomain.example.com
$ 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 https://labs.consol.de/de/development/git/2017/02/22/gitignore.html

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

or

$ 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 https://chris.beams.io/posts/git-commit/

• Separate subject from body with a blank line
• Limit the subject line to 50 characters
• Capitalize the subject line
• Do not end the subject line with a period
• Use the imperative mood in the subject line
• Wrap the body at 72 characters
• Use the body to explain what and why versus how

Further reading

https://git-scm.com/book/en/v2/

Git tutorial: http://www.flutterbys.com.au/stats/tut/tut19.1.html

Introduction (de language): http://pi.informatik.uni-siegen.de/lehre/Vertiefungspraktika/2016s/materials/slides/2016s_PEP_slides_git.pdf

Important commands: https://pgi-jcns.fz-juelich.de/pub/doc/git_gitflow.pdf

MS Azure git documentation https://docs.microsoft.com/en-us/azure/devops/repos/git

Install git on WSL. In a Bash prompt:

$ sudo apt install git

Location of config files: https://www.onwebsecurity.com/configuration/git-on-windows-location-of-global-configuration-file.html

Line ending issues: http://www.edwardthomson.com/blog/git_for_windows_line_endings.html

A quote from https://forum.kicad.info/t/how-to-clone-a-project/3878/4 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.pro 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:

• Submodules provide semi-fixed references from the super-project into sub-projects and are integrated into git. It is best used when the subproject:
• is developed by someone else, is not under the administrative control of the super-project and follows a different release cycle.
• contains code shared between super-projects (especially when the intention is to propagate bug-fixes and new features back to other super-projects).
• separates huge and/or many files that would hurt performance of everyday git commands.
• Subtrees causes the subproject repository to be imported into the super-project's repository to be a native part of the repository with full history, typically in a specific subdirectory of the super-project.
• Wrappers, which provide multi-repository management functionality to a super-project with associated sub-projects.

https://gist.github.com/gitaarik/8735255

Linux kernel example: https://git.wiki.kernel.org

https://git.wiki.kernel.org/index.php/SubprojectSupport

https://developer.atlassian.com/blog/2015/05/the-power-of-git-subtree/

How to include a Windows compare tool: https://www.sep.com/sep-blog/2017/06/07/20170607wsl-git-and-beyond-compare/

Last change: 2024-01-08
© 2002-2024 Dr. Thomas Redelberger redetho(a‍t)gmx.de

• Home
  • Projects
  • Documentation
    • SW Development
      • EMACS
      • Git
      • AVRASM
      • Graphics
    • Computing
    • Content
  • Site Map
  • Data Privacy