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
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.
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 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).
This chapter explain basic git command. Refer to the many excellent Git online resources.
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
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
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
All the time:
To update your branch with the latest :
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
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 \<<firstname.lastname@example.org>\> 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