How To Git

The whole project is developed for a GIT usage. If you are not familiar with git or how to commit, try the following tutorial first, to learn basic git commands: Interactive Tutorial Furthermore, it's necessary to understand the basic git flow or structure of this project, as multiple people are working on it at the same time.

How it works

The best practice for structuring a project is the following Git branching model.

Basically it says, that each repository should have two main repositories master and develop, and several feature branches, which get merged into the develop branch and the develop branch himself gets merged from time to time in the master, if it's considered stable. This model is also used for our project ContractVis. An example workflow is listed below:

1. Pull from develop branch, which contains always the latest stable version. (Don't commit directly to it! Except in specific cases!)
2. Create a feature_XXX branch, which should start with the keyword feature_. Assign a descriptive name for the branch using the CamelCase convention (What is CamelCase?).
3. Work on the feature branch locally and push it to the repository. (See next section for further details)
4. After you finished your work on the branch, create a Pull Request which gets merged into the develop/master branch, after a review.

DO's & DON'Ts:

• If you commit to devlop, only do it for hotfixes, where you are absolutely sure.
• Feature branches start always with feature_ and then the name in CamelCase.
• Create a pull request for your feature branch after its finished.
• Feature branches should only be related to one specific issue or one problem.
• More feature branches are better than less.
• As issues are created, make sure labels are assigned correctly.
• Try to help others with bugs and review code.
• Assign issues to persons who can fix them reliantly.

How to commit

It's recommended to use any IDE with Git integration for the commits, as it offers the best possibilities for version control and message committing. Before you commit make sure there are no errors and write a meaningful, but short message in one of the following formats: For a single change, which either references an issue or closes it.

Fixes Bug XXX and implements (refs #IssueNr.) (closes #IssueNr.)

For multiple changes, which fixed various stuff.

Multiple Changes:
* Fixes Bug XXX (refs #IssueNr.)
* Removes XXX (closes #IssueNr.)
etc. ...

---

Command Line:

Before we show an example commit with PyCharm and Visual Studio Code and the workflow behind it, we would like to show you some useful tips and commands, when working in the command line with git.

• If you are in a git directory or workspace of an git project, you can use the following command to get a basic information about the current state of files (changed, excluded, ready to commit, etc.).

git status

• To add a new created file to the git tracking (if not done automatically by your IDE) you need to do it with the following command.

git add exampleFile.txt

• Once files are changed they are in the staging area, where they still can be removed from the commit or reverted. In order to commit the files and changes, type the following, with a meaningful message.

git commit -m "Added XXXX and Fixed XXXX"

• If you want to add multiple files of the same type, you can use wildcards.

git add '*.txt'

• To browse the history of changes git also offers a handy feature, which is called the git log.

git log

• The push command tells git where to put the local files on the remote repository and which branch. The example pushes the files to the origin branch of the remote repo.

// -u tells git to remember the branches so we can use next time just git push
// origin is where we push
// master is the name of the local branch we are on     

git push -u origin master

• To get the latest changes you need to pull again from the repo.

// orgin is the remote branch where we pull from
// master is the name of the local branch we pull into

git pull origin master

• To view the changes of the most recent commit, compared to the current branch we can use the following command. To point to the most recent commit, we use the HEAD command.

git diff HEAD

• Another great use for the diff is to see the changes to starged files (the files which are in the pipeline for commiting).

git diff --staged

• Files can be removed aka unstaged by using a reset command.

git reset exampleFile.txt

• Files can also be changed back to what they have been before, by using the checkout command, as unstaging them only removes them from the commit pipeline.

git checkout --exampleFile.txt

• In order to create a new working branch, which later can be merged into the master branch, you can execute the following command.

git branch branchName

• After merging a feature branch into the master or main branch, you should clean it up.

git branch -d branchName

---

PyCharm

By using the IDE PyCharm, we have the advantage of having an integrated VCS (Version Control System). The system is well integrated into the IDE and will be explained shortly here. For more details, research on Pycharm and git usage. Here only the most important workflow for a sample project will be shown in the video below.

Showcase Video

Visual Studio Code

The IDE of our chocie is Visual Studio Code as it's fantastic and lightweight and offers huge customization as well as the advantage of having an integrated VCS (Version Control System). The system is well integrated into the IDE and will be explained shortly here. The showcase video will show you how to work on a sample project with Visual Studio Code.

Showcase Video