oblik / kirby-git
Shows you Git changes in the Kirby panel and allows you to add/commit/push them, manually or automatically.
Fund package maintenance!
OblikStudio
Installs: 9 055
Dependents: 0
Suggesters: 0
Security: 0
Stars: 84
Watchers: 9
Forks: 6
Open Issues: 13
Language:Vue
Type:kirby-plugin
Requires
- getkirby/cms: ^4
- getkirby/composer-installer: ^1.2
Requires (Dev)
This package is auto-updated.
Last update: 2024-10-26 13:21:36 UTC
README
For contributing instructions, please check CONTRIBUTING.md. Thanks!
Note: Once the Kirby 3.6 docs come up (especially the UI Kit ones), I'll be able to invest some time and add a few features I've planned for a while.
Kirby Git
Shows you Git changes in the Kirby panel and allows you to add/commit/push them, manually or automatically.
Installation
With Composer:
composer require oblik/kirby-git
Note: This plugin requires Git version 2.22.0
or above. Check how to update it on your server here.
Usage
In order to work successfully with this plugin (and Git in general), you need separate branches in order to avoid overwriting history.
Let's say your repository is hosted on GitHub. This means you have a remote called origin
and it points to that GitHub repo. Example setup:
live
is the branch that is checked out on the live server. Content changes are pushed toorigin/live
from the panel via this plugin. You should never push toorigin/live
by other means. This would allow editors to always be able to commit and push new changes.dev
is the branch where you do development work locally on your machine. You can freely make both site changes and content changes and push them toorigin/dev
for other developers to pull.master
is where you merge the other two branches. You pull content changes fromorigin/live
, merge them with your local changes ondev
, resolve conflicts locally, and push toorigin/master
.
Whenever someone in the panel issues a pull, the origin/master
branch will be fetched and merged with the local live
on the server if, and only if a fast-forward merge is possible. This means that if there are changes on live
that are not reflected on origin/master
, the merge will fail.
Example flow:
- You push C1 (commit 1) and C2 from your
dev
toorigin/dev
- Editors push C3 and C4 from
live
toorigin/live
- You pull C3 and C4 from
origin/live
to your locallive
- You merge your
master
with yourdev
and yourlive
, resulting in a merge commit C5 - Your
master
now has all C1, C2, C3, and C4 and you push it toorigin/master
- Editors will be able to pull
origin/master
and fast-forward to C5, which has your C1 and C2
If editors created a new commit C6 on their live
before merging with origin/master
, the merge would have failed because C6 does not yet exist on origin/master
. So they push C6 to origin/live
, you pull it, merge it with master
, and push it to origin/master
. After that, editors would be able to pull.
Config
The plugin expects a repo to already be initialized and set up. You just give a path to that repo and check out the branch it should use.
Options for the plugin are specified with dot notation in site/config/config.php
. For example:
return [ 'oblik.git.repo' => '/path/to/repo', 'oblik.git.merge' => 'master', ... ];
bin
What executable to use. You might need to specify this option if there are multiple versions of Git on the machine.
Default: git
repo
Path to a folder containing a Git repo (a .git
folder).
Default: kirby()->root('index')
(the project folder)
remote
What remote to use for pulling from and pushing to remote branches.
Default: origin
merge
What branch to be used for merging when issuing a pull.
Default: master
hooks
An array of Kirby hooks to use as a trigger for git add
and git commit
. Example:
return [ 'oblik.git.hooks' => [ 'site.update:after', 'page.update:after' ] ];
With the above config, a new commit will be created any time a page or the site object is updated. However, this could bloat your repository with hundreds (or even thousands) of commits. You could use a hook like user.login:after
that gets triggered more rarely.
Default: null
log
Absolute path to a file where each command executed by this plugin will be logged. Example:
return [ 'oblik.git.log' => '/path/to/kirby-git.log' ];
Logs will look like this:
git -C /var/www/site status -u --porcelain 2>&1
git -C /var/www/site rev-list --count master 2>&1
git -C /var/www/site log origin/master..master --format=%h 2>&1
git -C /var/www/site log master --pretty=format:"%h|%an|%ae|%ad|%s" --skip="0" --max-count="15" 2>&1
...
Default: false
Section
For displaying a summary of Git changes, you could use the git
section in a blueprint:
title: Page sections: changes: type: git headline: Git Status
View
In the panel view, you can add, commit, and push changes in a very simple manner. Just three columns and three buttons:
REST API
The plugin uses Kirby's REST API to provide a means for the panel view to communicate with PHP. You can use it as well! Check the various routes here.
API
You can work with Git via the Git
class as well. For example:
use Oblik\KirbyGit\Git; $git = new Git(); $git->add(); $git->commit('my message'); $git->push();