A Super Short Introduction to Git

Project page | Mailing list | Git repository | Trackers | Sessions Documentation

#Super short introduction to git

Caveat: All the information you'll find here is based on my current understanding of how git works.

Git has excellent documentation that you can call from the command line with man git, git --help, etc. It is not always easy to understand if you are not used to version control systems, but you'll eventually get used to it. Don't hesitate to ask questions. The links I provide at the end are probably the best reference you can possibly find on the net.

People say that the part where git shines is in its ability to work with branches. Let's see what that means.

A very simple workflow would be:

enter a branch from the main repository
branch off the data to create a personal "work" branch
make modifications to the files within that branch
merge that code with the original code
resolve possible conflicts with data that was modified in the original branch while you were working on yours
push your work to be included in the main repository

When you work on a repository, you must expect that somebody else is also working at the same time on that repository in a way that is going to conflict with your work.

Some of their modifications will conflict with yours. Some won't, but that's because you're lucky. Check p. 61 and following of ProGit to have detailed information on that workflow.

#Clones are real

Everything starts with git clone which is the command that will clone a given project to your local machine.

In our case, we need to

git clone git@git.sr.ht:~brandelune/omegat-as-a-book

to be able to push back our modifications here (assuming you have write access, which you can request).

If you just want to play with this repository locally

git clone https://git.sr.ht/~brandelune/omegat-as-a-book

will suffice.

#Moving from branch to branch

The omegat-as-a-book repository currently has two branches:

main contains the readme and the OmegaT code

wiki contains the wiki (including this file) and none of the code

go to the wiki branch when you want to modify the wiki:

git checkout wiki
go back to the main branch when you want to work on the original code:

git checkout main

When you enter a different branch, Git actually hides or shows the files that are available in that branch. Branches can contain totally different things, even different code bases.

#Alternate command to switch branches

The above checkout command also has other uses that are beyond the scope of this mini-introduction. Since version 2.23, a new, less confusing git switch command has been introduced for working with branches.
Moving to the wiki branch: git switch wiki
Going back to the original code: git switch main
Creating a new branch: git switch -c [branch name]

More information on the switch command can be found in this Stack Overflow question as well as the following article introduced in a comment from that question.

#Working on your own branch(es)

You can create your own local branches, and their contents will be based on the content of the branch you "branch off" from.

create and enter a local branch to work on a given feature:

git checkout -b myFeatureBranch
do your modifications and then, to see what has been modified:

git status

If you are happy with the modifications:

add the files that need to be updated in the repository registry:

git add path/to/files/you/want/to/register

Once you've added all the files related to a given sub-feature:

If you want to leave the branch but you have some unregistered work that you want to keep, you can temporarily put the contents in a stash.

stash away the changes without permanently registering them:

git stash

You can call back and apply the stashed work to the same branch but later, over some other work, or in a different branch if you think it is more relevant there.

apply the stashed work to the current branch:

git stash apply

Now you need to merge your work with the original branch, and eventually resolve conflicts if something has happened upstream that steps on your data while you were working. Since you are alone working on your machine, that is unlikely to happen.

What is possible, though, is that you made modifications on a file in the original branch, entered a new branch and made modifications on that same file. In that case, you'll have to massage the two modifications so that they don't overlap in irreconcilable ways.

go back to the branch your branched off from:

git checkout originalBranch
merge the contents of that branch with the contents of your branch

git merge myFeatureBranch

If there are no stepping on toes, you will have no Automatic merge failed; fix conflicts and then commit the result. error.

If you do have a merge error message, git will automatically add markers inside the conflicting parts of the files so that you can open the files in a text editor, fix the conflicting parts and commit/merge your modifications again.

The markers will look like that:

<<<<<<< HEAD:theModifiedFile
The conflicting content.
=======
Your content.
>>>>>>> myFeatureBranch:theModifiedFile

Edit the files, git add them, git commit them again, and you're done.

Then, you want to push your modifications from your local machine to the sr.ht server from where the other participants can pull your modifications and make them theirs.

Here again, if modifications have already been pushed upstream, you'll end up with conflicts. The resolution is very similar to what we've done already.

pull the contents of the remote branch to your local copy

git pull

If there are merging issues, solve them as we just did.

push your modifications to the remote branch:

git push

#Et voilà!

This short tutorial should be enough to give you an idea of how to work with git on a daily basis. If you are careful enough, you should not need more commands than what is described above. If you want to know more, check the references that are linked to below.

#If you want to know more about git

Project page | Mailing list | Git repository | Trackers | Sessions Documentation