GIT101: the basic basics

  • GIT manages the changes to the contents of a folder, including subfolders. Such folder managed by git is called a (git-)repository, and can be compared to a ’Project’ in some other systems, or a ’Course/Community’ in Toledo: it can have users with associated rights, and has certain global properties and configuration.

    The ’management’ of git takes place completely in a subfolder .git which is not important for users. A ’repository’ is therefore a folder-with-a-suitable-git-managed-.git-subfolder. There are no external dependencies with registries, web services, versions of git, etc.

  • You can use such folder just like any other folder, with all the tools of your choice such as Notepad, Windows Explorer, command line, TexStudio. The only thing you must NOT do is change the .git subfolder yourself.
  • The command git commit creates a ’savepoint’ for the entire folder. Such a savepoint is called a ’commit’, and gets an internally used identifier of the form , called ’commit SHA’, and a description given by you. GIT remembers that particular version forever (by making changes to the .git folder). (However, see below for a small complication regarding the ’staging’ of changes ...).
  • The command git log shows the history of all changes.
  • All of this typically happens locally on your own PC.
  • The command git clone is the starting point for most users: ’git clone’ copies an existing repository to your PC. KU Leuven manages a large collection of repositories (or projects) at https://gitlab.kuleuven.be, and there are more than 200,000,000 on the public service https://github.org. The version from which you clone your own copy is called the origin by GIT.
  • The command git fetch retrieves all changes from the server (thus from ’origin’) to your PC, but only stores them in the .git folder, and thus does NOT change the files themselves on your PC. Your local git now knows what has changed on the server.
  • The command git pull also retrieves all changes from the server, but also brings your folder up-to-date as long as there are no conflicts with any changes you may have already made. With good hygiene, such conflicts are very rare, and if they do occur, GIT helps you resolve them.
  • The command git push sends all changes you have committed to the server (thus to ’origin’), and warns in the exceptional case that there would be conflicts with changes made by others in the meantime.
  • GIT is used for repositories with very many files that are changed fairly intensively by very many people, and provided good hygiene, this works perfectly. A LaTeX project with a dozen co-authors is a joke for a system like git. Provided, of course, that the dozen authors learn to use the system correctly.
  • We are only one page in, and have already lied at least once: ’git commit’ does not make a savepoint of all changes on your PC, but only of the changes you stage through ’staging’. This is very useful for spreading some changes over two commits (for example, ’typo’ in intro.tex and ’new method to explain infinitesimals’ in derivatives.tex), or also for not committing some already changed files because more changes are needed.
  • The command git add adds the current version of files in your folder to your staging area, and prepares them for the next commit.
  • The command git status shows the status of your folder at any time: are the files identical to, older or more recent than the current version according to git.
  • . The command git diff shows the differences between files, for example between your version and that of git, but also between historical versions or versions in different branches (see below).
  • The list of successive commits gives the most basic case a history of the project:
  • A file is typically ’unmodified’ when it is just pulled, becomes ’modified’ when you change it, and becomes ’staged’ after a ’git add’. A file becomes ’untracked’ when you remove it with git remove (it will be removed from the next commit, but of course it will still be in the history). A new file is ’untracked’ until you add it with ’git add’.
  • A second lie: git does not necessarily manage all files in your folder: through a configuration file .gitignore, for example, you can explicitly ignore log files and the like. For LaTeX, there is a whole collection of intermediate files to be ignored: they do not end up in git. Typically, the pdf is not stored in git either.
  • You prepare changes with ’git add’, make a (local) savepoint with ’git commit’, and examine your copy of the repository with ’git status’, ’git log’ and ’git diff’.
  • You use an existing project via ’git clone’, and then synchronize with the central version of the repository using ’git pull’ (from server to your PC) and ’git push’ (from your PC to the server). Exceptionally, you use ’git fetch’.

GIT, gitlab, github and gitwhatelse

  • git is the general name of this version control system, which determines, among other things, the structure of the .git folder.
  • git.exe (or git in Linux) is the name of a (command-line) program that implements the entire official functionality of git (clone, push, pull, add, commit, ...)
  • github.org is on the one hand a publicly available collection of repositories, and on the other hand a website/web service that offers most of the git functionality through a web interface.
  • github.org has added additional functionality (actions, merge requests, …)
  • github.org is also developing a simple Windows program with the basic functionality of Git: Github Desktop. This is an alternative to the command-line program ’git.exe’. There are many other alternative GUI’s as well.
  • for Ximera we do not use github.org, unless perhaps for Github Desktop. Any other GIT client is just as good.
  • gitlab.com is an alternative, say competitor, to github.org. They offer their web software to customers. For Ximera we do not use the gitlab.com website.
  • https://gitlab.kuleuven.be is the KU Leuven collection of git repositories, so that such a collection can be offered on KU Leuven infrastructure under KU Leuven management via KU Leuven accounts.
  • Ximera makes intensive use of the KU Leuven gitlab service, not only as a central location for the repositories, but also for the so-called ’Continuous Integration/Continuous Deployment’ functionality that allows the LaTeX code to be automatically verified and built with each commit in different versions (online, with/without answers, also possibly in color/black-and-white or with extra features, subtitles or qrcodes)

GIT102: get to work

  • Install a client (e.g., ’Github Desktop’ or ’Git For Windows’)
  • Go to gitlab.kuleuven.be and select the https URL of the desired repo via the blue ’Clone’ button.
  • Choose a suitable location on your PC (preferably a local disk, backups are not necessary because you will push regularly anyway). Usually ’Documents/git’ is a very suitable choice.
  • git clone https://gitlab.kuleuven.be/monitoraat-wet/zomercursus-wiskunde.git creates a folder zomercursus-wiskunde with all the LaTeX code of the most recent version of the summer course modules
  • git checkout ZomercursusA2020 : you now have the version used to create the A-programme of the Summer Course 2020.
  • git checkout archief__xelatex : you now have a version with the modules of the Summer Course 2019 that should build with xelatex.
  • git checkout master : you now have the latest ’official’ so-called master version of all code.
  • Find a (math, typing or layout) mistake and correct it.
  • git status (you will see the file you changed in red)
  • git add functies/intro.tex (or the file you edited)
  • git status (now you will see the file you changed in green: green means staged, ready to commit)
  • git commit -m ’Faut xxx improved’ (you are now creating a new savepoint in the project, for now only on your PC. Until (and even if ) you don’t push, nobody knows that... )
  • git status (you now see that you are one commit ahead of ’origin’, i.e., ahead of the version on the central server from which you cloned the repo)
  • git push (your changes are now on the server and can be viewed, for example, on gitlab.kuleuven.be. Automatically, a so-called ’pipeline’ will have started under CI/CD which will pdflatex the complete code). Others will have to ’git pull’ to see your changes.
  • Tired but satisfied, take a rest.
  • git pull (get any changes on the server)
  • Make some more changes, whether spectacular or not
  • git add, git commit, git push
  • If the changes were indeed spectacular, we immediately limit your rights. After all, you should have made a ’branch’. But that will be explained later.
2024-07-15 10:41:03