Git --work-tree Argument Should be repoPath not RepoWorkDir

[sjv0]

trafficstars

My dokuwiki data dir is not at the root level of my repo, so my repoWorkDir is a few levels deeper than my repoPath.

If I enter these two configuration settings as documented, git gets pretty confused and the commit makes quite a mess of my repository. The problem is that --work-tree has been given a path that's not a git working tree. It's a directory a few levels within one.

It looks to me as though the plugin should be setting --work-tree to repoPath. I'm not even sure that the plugin needs the repoWorkDir configuration variable at all. dokuwiki knows where the data files are thanks to the $conf['datadir'] and $conf['mediadir'] settings in dokuwiki/conf/local.php. When a file is modified, its full path is provided to the plugin, so the git commands just work.

I've found that if I set repoWorkDir to the same path as repoPath, everything works correctly.

[woolfg]

thanks @sjv0 - if I can recall correctly in some setups you can have different paths, but I am also not 100% sure about that. @mhoffrog do you know more details about it?

[mhoffrog]

@sjv0 @woolfg In my dokuwiki configs I did configure repoPath and repoWorkDir the same. To be honest I did not yet get fully how a scenario with repoWorkDir being different and maybe somewhere beyond repoPath would work and what would be the benefits. @sjv0 - can you provide me with the details of your dokuwiki folder structure and what was your initial config that did not work ?

[woolfg]

maybe @danny0838 can remember the reason who added it in #11? I can't find a proper reasoning but I think we have talked about it somewhere.

[sjv0]

@sjv0 - can you provide me with the details of your dokuwiki folder structure and what was your initial config that did not work ?

Sure, @mhoffrog. My dokuwiki dir is at /usr/local/www/nginx/dokuwiki and my local git workarea is at /usr/local/dev/main. My documentation files live a few levels deeper in that repository at /usr/local/dev/main/docs/dokuwiki/data/pages and /usr/local/dev/main/docs/dokuwiki/data/media.

My /usr/local/www/nginx/dokuwiki/conf/local.php setup contained the following paths when I had the problem:

$conf['plugin']['gitbacked']['repoPath'] = '../../../dev/main/';
$conf['plugin']['gitbacked']['repoWorkDir'] = '../../../dev/main/docs/dokuwiki/data/';
$conf['datadir'] = '/usr/local/dev/main/docs/dokuwiki/data/pages';
$conf['mediadir'] = '/usr/local/dev/main/docs/dokuwiki/data/media';

When I saved a change to my start page, the following git add command was executed:

/usr/local/bin/git --work-tree '/usr/local/www/nginx/dokuwiki/../../../dev/main/docs/dokuwiki/data/' -c user.email="<[[email protected]](mailto:[email protected])>" -c user.name="Me" add /usr/local/dev/main/docs/dokuwiki/data/pages/start.txt -v

This is a problem because the path in the above --work-tree argument is three levels deep within my git workarea. There's no .git directory there. The resulting commit made quite a mess of my files.

When I changed repoWorkDir to match repoPath, everything worked as expected because git was given a --work-tree argument of /usr/local/www/nginx/dokuwiki/../../../dev/main/, which is my actual git workarea with a .git directory in it.

[danny0838]

I believe it's for an additional flexibility for some possible configurations like:

1. Making pages and media be different subpaths within the git repo.

For example, one may want a directory structure like this:

/path/to/dokuwiki/.git
/path/to/dokuwiki/data
/path/to/dokuwiki/data/pages
/path/to/dokuwiki/data/media

and want data/pages and data/media be pages and media within the git repo, which can be achieved by setting $conf['plugin']['gitbacked']['repoPath'] = '/path/to/dokuwiki' and $conf['plugin']['gitbacked']['repoWorkDir'] = '/path/to/dokuwiki/data'.

2. Making git repo path be independent to the git working tree.

For example, one may want a directory structure like this:

/path/to/myrepos/dokuwiki/.git
/path/to/dokuwiki
/path/to/dokuwiki/data
/path/to/dokuwiki/data/pages
/path/to/dokuwiki/data/media

which can be achieved by setting $conf['plugin']['gitbacked']['repoPath'] = '/path/to/myrepos/dokuwiki' and $conf['plugin']['gitbacked']['repoWorkDir'] = '/path/to/dokuwiki'.

In other (probably more common) cases one can simply set $conf['plugin']['gitbacked']['repoWorkDir'] equal to $conf['plugin']['gitbacked']['repoPath'], which won't cause any issue.

To prevent a confusion, consider defaulting $conf['plugin']['gitbacked']['repoWorkDir'] to empty or null value, in which case $conf['plugin']['gitbacked']['repoPath'] will automatically be used.

[woolfg]

thank @danny0838 for the fast and very detailed reply.

For me the prefered improvement would be:

To prevent a confusion, consider defaulting $conf['plugin']['gitbacked']['repoWorkDir'] to empty or null value, in which case $conf['plugin']['gitbacked']['repoPath'] will automatically be used.

[mhoffrog]

@sjv0 many thanks for the details of your config. Stupid question: Did you let the repoPath .git config know about the worktree - by using the git worktree add ... command ? You can check, if your .git folder contains the .git/worktrees folder.

[sjv0]

Hi @mhoffrog, not a stupid question at all - I didn't even know about git worktrees until I read this comment from you. I have only ever used git branches. Is the expectation that a worktree needs to be created within the git workarea for gitbacked to use? If so, I need to look more deeply into this.

Can I ask what benefit that would give over just having gitbacked add and commit my changed files, then auto-push them? All I need is to have the pages and media of my wiki automatically committed and pushed to a directory in my development tree whenever changes are made via the wiki. So far I've managed to achieve this by adding a git hook to my repository to ensure the workarea is always up-to-date (it issues a git pull after every commit), and setting repoPath and repoWorkDir to the top level of the repository. I've got the auto-push option turned on as well. It's working exactly as I want it to right now, but if git workareas would make it better somehow I'm keen to know more!

Thanks so much for your time.

[mhoffrog]

Hi @sjv0, many thanks for that clarification. This was also my assumption for your use case. So there is a lot of confusion around this git work tree feature. And you are right - in your use case where you just have your DokuWiki content to be tracked by git, it makes no sense to use a work tree at all.

A scenario, where the work tree feature would make sense, could e.g. be when source code and doku is maintained in the same git repo. In this case one would probably create a doku_branch on which DokuWiki would maintain the documentation. This branch then has to be merged into the projects release or master branch from time to time. In this case you would then checkout the master branch of the repo in the root of the repo folder and you would checkout the doku_branch in a separate worktree above or beside of the repo root. Then you would have to configure gitbacked with a repoWorkDir being different to the repoPath. On the other hand side, if there is no development done on the machine, where DokuWiki is hosted, then it would be sufficient to only checkout the doku_branch. In this case there would also be no need to use the work tree configuration.

By the way - there are good examples / explanation for git work-tree here: Experiment on your code freely with Git worktree

As @woolfg did comment above already - the best improvement would be to default the repoWorkDir to empty string and to omit the --work-tree option in the git command in this case.

[sjv0]

Thank you for the clarification, @mhoffrog.

If you were going to omit the --work-tree argument, wouldn't you still need to at least provide -C repoPath? Otherwise I don't see how the commit is going to know where the repository is.

[mhoffrog]

If you were going to omit the --work-tree argument, wouldn't you still need to at least provide -C repoPath?

@sjv0 This will work, since each git command is performed with the php method proc_open and repoPath being passed as absolute directory for parameter $cwd (the initial working dir for the command).

[mhoffrog]

Addressed by PR #83 - --work-tree is ommited now if repoWorkDir is empty.