Git

Overview

The Git source control version is not a core component of the PunchPlatform, but it is strongly recommended to use git on your punchplatform production environment for traceability/rollbacks purpose of the punchplatform configuration (both platform level and tenants channels/jobs configuration level)

You should setup and use a central Git repository to store all your configuration changes when you :

• deploy, update and operate a PunchPlatform configuration
• configure log channels of a Punchplatform
• develop core PunchPlatform modules
• write, update or deploy log parsers

This chapter introduces what are GIT repositories, and what the Git commands you should master

Note

Git is sometimes perceived as complex. This is a misperception: Git is powerful, flexible and safe. Hence the need to make sure you only use Git command you understand.

Repositories

Git repositories contain all the successive versions of a filesystem folder content.

A git repository can be synchronized with other: changes can be from another repository. Git repositories exist in two variant :

• Working repositories :

  contain editable content, i.e. a used can see, update, add or delete files. It typically contain the latest version of a branch. It can however contain uncommitted changes. On such repository, the previous versions are stored in a hidden '.git' folder, located in the repository root folder.

• Bare repositories :

  are used only as a shared storage holding referenced versions. It does not contain a working copies of the files. If you go in there , you will only find git storage files.

In classical Punchplatform production setups, a bare repository has been set up (using git init --bare), and contains all the versions of the PunchPlatform configuration files, but no user actually work in this directory.

Working repositories are used by operators for performing configuration changes, using: - PunchPlatform cluster deployment tool punchplatform-deployer.sh - PunchPlatform administrators/operators command-line environments used to configure/operate log channels

On the contrary, the punchplatform kibana administration plugin does NOT use git. It only works on the 'reference' applicable version of the punchplatform configuration, which is the one currently stored in the admin zookeeper cluster. (cf. punchplatform-putconf.sh and punchplatform-getconf.sh).

Git Primer

This chapter explain basic git command. Refer to the many excellent Git online resources.

Basics

A git repository is a plain directory. If you don't have one already at hand, create any directory, put some file in it, go in there and type

git init

now you have a local git repository. In the rest of this chapter we take the PunchPlatform documentation directory as example repository. Assuming you have access to the Thales GitLab repository, you can clone it as follows

git clone https://gitlab.thalesdigital.io/punch/punchplatform-internal/pp-documentation.git
cd pp-documentation

Branches

When First, list branches and know where you must be working.

# list all branches
#     git branch     : show only local branches
#     git branch -r  : show only remote branches
#     git branch     : show them all
#  

git -branch
  origin/HEAD -> origin/master
  origin/craig-stable
  origin/master

This is just an example. Here we have a master branch Since we never work on the master branch it's a good idea you start retrieving and switching to the development branch.

git checkout craig-stable

Daily working

All the time:

git status

To update your branch with the latest :

git pull

What to do if you have a conflict preventing you to pull or commit ?

# This will launch a diff tool like meld depending on what you have
git mergetool

Add the changes you are happy with in your local staged area, so that you can commit them:

git add only-what-is-needed

Commit your changes:

# recheck !
git status

# this is local only. Nothing is sent to the remote repo. 
# Hence it is not saved
git commit -m "short english description you what you did"

Send your changes:

git push
# Will not work if you have conflicts. Go back to git mergetool

Versions

We use tagging to tag working version with a major.minor.increment scheme. This versioning is only internal to PunchPlatform and has no relationship with anything known outside the PunchPlatform team.

To list the versions:

git tag v0.0.2

To see what's in a version

git show v0.0.1 Tagger: Dimitri Tombroff
 \<<dimitri.tombroff@gmail.com>\> Date: Tue May 6 17:57:36 2014 +0200

 first working dev release : hourra

To tag a new version

git tag -a v0.0.3 -m 'MANDATORY: short english message explaining
 what it is'

Workings with friends

Sometimes one of us adds a branch, for example for a new feature or a fix. That branch may be visible on the remote repo, but not yet using the git branch command (not even with the '-r'). To list everything known on the remote repo you can do:

git ls-remote     
017850aba74e978e24a341a75b73f45af506a654    HEAD
c84488e5ebd7a74f66a024d8d52fdfa3a42a3b4c    refs/heads/development
12fdfc31b7bab7d4d88df1196f44494be305fe5a    refs/heads/feature/cedric-new-exciting-feature
017850aba74e978e24a341a75b73f45af506a654    refs/heads/master

If you see there some branch you need to work with, how can you catch up ? Say you want to download and track the new Cedric feature ? DON'T PULL IT: that would automatically merge its content to your current branch (probably the development). It's not what you want. Instead do this:

git checkout --track origin/feature/cedric-new-exciting-feature

So that you can see that branch locally, and work with it.

source

git branch -a
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/development
  remotes/origin/feature/david-new-exciting-feature
  remotes/origin/master