diff --git a/README.md b/README.md index 5abb0abd3bf274e63dae94fc9596eefb720e0d13..d1cb5edcbe4b73f0a20c6b84dc0b11de639a35a6 100644 --- a/README.md +++ b/README.md @@ -38,11 +38,39 @@ Different Websites to host a `git` repository: - Github (Google): <a href="https://github.com" target="_blank">https://github.com</a> - Bitbucket (Atlassian): <a href="https://bitbucket.org" target="_blank">https://bitbucket.org</a> -Especially if a project is developed/maintained by more then one person, it is useful to determine a develepment strategy (branching model) to keep the history clean and readible. +###### Git Workflow + +If a project is developed/maintained by more then one person, it is useful to determine a develepment strategy (branching model) to keep the history clean and readible. + +**Groups:** If the project is not tied to a single person, or if multiple people are responsible to maintain the project, it might be useful to create a <a href="https://docs.gitlab.com/ee/user/group/" target="_blank">GitLab Group</a>. This way the project itself is not tied to a specific user account and additional projects may be linked under the same group as well. (See the <a href="https://gitlab1.ptb.de/pythia/" target="_blank">PyThia Group</a> as an example.) +In particular, it might be useful to create a Git group for your working group. +This way you can easily grant access to every Git repository in your workgroup to everyone of your workgroup. +You can even define different roles, to e.g. prevent specific members (e.g. students) to push to certain branches (e.g. main branch of your PhD repository). + +**Branching models:** +A Git workflow or branching model is essentially fixing a way to create new branches and enforce certain criteria for different branches. +This way everyone working with the code, either through usage or contribution, knows how to obtain a stable version of the software, checkout the latest development stages or add features in a reproducable way. +There exist a multitude of common branching models, neither of them being better then the other. +For examples, see either the <a href="https://docs.github.com/en/get-started/quickstart/github-flow" target="_blank">GitHub flow</a> model or the <a href="https://gitlab1.ptb.de/pythia/pythia/-/blob/development/DEVELOPERS.md#git-workflow" target="_blank">branching model of PyThia</a>. +A good overview of different git workflows can also be found <a href="https://medium.com/javarevisited/5-different-git-workflows-50f75d8783a7" target="_blank">on this website</a>. + +Here are some examples: + 1. If only you are working on your repository and if you ever only add new things, you can use only one branch (main) to build your code. + 2. If you want to always have working version of your code, you can work linearly on a `development` branch and merge that into the `main` branch only if everything works. + 3. If you work on different features simultaneously or want to test things out, you can create `feature-branches`, code on them and merge them into the `development` branch once everything works in them. + +**Tips:** + 1. You can "squash" commit messages of feature branches, if you are not interested in keeping every "Bugfix" commit message in your history. + 2. When working with (a lot of) different branches, make sure you can easily see which branch you are on. + For example your can change the layout of your bash command line to show the current branch: + + +###### Git Commit Messages + To keep the Git history clean and understandable, it is best practice to follow a consistent commit style guide, as e.g. the one discussed in <a href="http://who-t.blogspot.com/2009/12/on-commit-messages.html" target="_blank">this blog post</a>. As an overview on the common git commit message style, <a href="https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html" target="_blank">this cheat sheet</a> might help a lot. @@ -53,10 +81,7 @@ As an overview on the common git commit message style, <a href="https://tbaggery - Any line of the commit message cannot be longer than 72 characters! This allows the message to be easier to read on GitLab as well as in various git tools. -Another important thing when developing code with multiple developers, maintainers and/or users is to choose (and specify) a branching model. -This way everyone working with the code, either through usage or contribution, knows how to obtain a stable version of the software, checkout the latest development stages or add features in a reproducable way. -There exist a multitude of branching models, neither of them being better then the other. -For examples, see either the <a href="https://docs.github.com/en/get-started/quickstart/github-flow" target="_blank">GitHub flow</a> model or the <a href="https://gitlab1.ptb.de/pythia/pythia/-/blob/development/DEVELOPERS.md#git-workflow" target="_blank">branching model of PyThia</a>. +###### . gitignore To keep only the relevant information in your repository, you should specify which files should not be tracked by `Git`. To do so, simply add a `.gitignore` file to your repository root.