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
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:
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.
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 firstname.lastname@example.org:~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
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.
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
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.
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:
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:
register your changes locally:
git commit -m "nice commit message"
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:
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
If there are merging issues, solve them as we just did.
push your modifications to the remote branch:
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.