rewrite readme
This commit is contained in:
parent
23e78ec886
commit
68cbf311b8
145
README.md
145
README.md
|
|
@ -1,119 +1,94 @@
|
|||
# gitlabfs
|
||||
# gitforgefs
|
||||
|
||||
`gitlabfs` allows you to mount and navigate Gitlab groups and user personal projects as a FUSE filesystem with every groups represented as a folder and every projects represented as a symlink pointing on a local clone of the project.
|
||||
*Formerly gitlabfs*
|
||||
|
||||
Partial output of `tree`, truncated and with a max of 4 levels:
|
||||
`gitforgefs` allows you to mount and navigate git forges (Github, Gitlab, Gitea, etc.) as a [FUSE](https://github.com/libfuse/libfuse) filesystem with every groups, organization, and users represented as a folder and every repositories represented as a symlink pointing on a local clone of the project. This is helpful to automate the organization of your local clones.
|
||||
|
||||
To help illustrate, this is the output of `tree` in a filesystem exposing all the repositories of a github user.
|
||||
```
|
||||
$ tree -L 4
|
||||
$ tree
|
||||
.
|
||||
├── projects
|
||||
│ └── gitlab-org
|
||||
│ ├── 5-minute-production-app
|
||||
│ │ ├── deploy-template -> /home/marchambault/.local/share/gitlabfs/gitlab.com/22487050
|
||||
│ │ ├── examples
|
||||
│ │ ├── hipio -> /home/marchambault/.local/share/gitlabfs/gitlab.com/23344605
|
||||
│ │ ├── sandbox
|
||||
│ │ └── static-template -> /home/marchambault/.local/share/gitlabfs/gitlab.com/23203100
|
||||
│ ├── allocations -> /home/marchambault/.local/share/gitlabfs/gitlab.com/684698
|
||||
│ ├── apilab -> /home/marchambault/.local/share/gitlabfs/gitlab.com/2383700
|
||||
│ ├── architecture
|
||||
│ │ └── tasks -> /home/marchambault/.local/share/gitlabfs/gitlab.com/22351703
|
||||
│ ├── async-retrospectives -> /home/marchambault/.local/share/gitlabfs/gitlab.com/7937396
|
||||
│ ├── auto-deploy-app -> /home/marchambault/.local/share/gitlabfs/gitlab.com/6329546
|
||||
│ ├── auto-deploy-helm -> /home/marchambault/.local/share/gitlabfs/gitlab.com/3651684
|
||||
│ ├── auto-devops-v12-10 -> /home/marchambault/.local/share/gitlabfs/gitlab.com/18629149
|
||||
│ ├── backstage-changelog -> /home/marchambault/.local/share/gitlabfs/gitlab.com/7602162
|
||||
│ ├── blob-examples -> /home/marchambault/.local/share/gitlabfs/gitlab.com/3094319
|
||||
│ ├── build
|
||||
│ │ ├── CNG -> /home/marchambault/.local/share/gitlabfs/gitlab.com/4359271
|
||||
│ │ ├── CNG-mirror -> /home/marchambault/.local/share/gitlabfs/gitlab.com/7682093
|
||||
│ │ ├── dsop-scripts -> /home/marchambault/.local/share/gitlabfs/gitlab.com/19310217
|
||||
│ │ ├── omnibus-mirror
|
||||
│ │ └── tr-test-dependency-proxy -> /home/marchambault/.local/share/gitlabfs/gitlab.com/20085049
|
||||
│ ├── charts
|
||||
│ │ ├── apparmor -> /home/marchambault/.local/share/gitlabfs/gitlab.com/18991900
|
||||
│ │ ├── auto-deploy-app -> /home/marchambault/.local/share/gitlabfs/gitlab.com/11915984
|
||||
│ │ ├── components
|
||||
│ │ ├── consul -> /home/marchambault/.local/share/gitlabfs/gitlab.com/18663049
|
||||
│ │ ├── deploy-image-helm-base -> /home/marchambault/.local/share/gitlabfs/gitlab.com/7453181
|
||||
│ │ ├── elastic-stack -> /home/marchambault/.local/share/gitlabfs/gitlab.com/18439881
|
||||
│ │ ├── fluentd-elasticsearch -> /home/marchambault/.local/share/gitlabfs/gitlab.com/17253921
|
||||
│ │ ├── gitlab -> /home/marchambault/.local/share/gitlabfs/gitlab.com/3828396
|
||||
│ │ ├── gitlab-runner -> /home/marchambault/.local/share/gitlabfs/gitlab.com/6329679
|
||||
│ │ ├── knative -> /home/marchambault/.local/share/gitlabfs/gitlab.com/16590122
|
||||
│ │ └── plantuml -> /home/marchambault/.local/share/gitlabfs/gitlab.com/14372596
|
||||
│ [...]
|
||||
└── users
|
||||
└── badjware
|
||||
└── test_project -> /home/marchambault/.local/share/gitlabfs/gitlab.com/23370783
|
||||
└── badjware
|
||||
├── aws-cloud-gaming -> /home/marchambault/.local/share/gitforgefs/github.com/257091317
|
||||
├── certbot -> /home/marchambault/.local/share/gitforgefs/github.com/122014287
|
||||
├── certbot-dns-cpanel -> /home/marchambault/.local/share/gitforgefs/github.com/131224547
|
||||
├── certbot-dns-ispconfig -> /home/marchambault/.local/share/gitforgefs/github.com/227005814
|
||||
├── CommonLibVR -> /home/marchambault/.local/share/gitforgefs/github.com/832968971
|
||||
├── community -> /home/marchambault/.local/share/gitforgefs/github.com/424689724
|
||||
├── docker-postal -> /home/marchambault/.local/share/gitforgefs/github.com/132605640
|
||||
├── dotfiles -> /home/marchambault/.local/share/gitforgefs/github.com/192993195
|
||||
├── ecommerce-exporter -> /home/marchambault/.local/share/gitforgefs/github.com/562583906
|
||||
├── FightClub5eXML -> /home/marchambault/.local/share/gitforgefs/github.com/246177579
|
||||
├── gitforgefs -> /home/marchambault/.local/share/gitforgefs/github.com/324617595
|
||||
├── kustomize-plugins -> /home/marchambault/.local/share/gitforgefs/github.com/263480122
|
||||
├── librechat-mistral -> /home/marchambault/.local/share/gitforgefs/github.com/753193720
|
||||
├── PapyrusExtenderSSE -> /home/marchambault/.local/share/gitforgefs/github.com/832969611
|
||||
├── Parsec-Cloud-Preparation-Tool -> /home/marchambault/.local/share/gitforgefs/github.com/258052650
|
||||
├── po3-Tweaks -> /home/marchambault/.local/share/gitforgefs/github.com/832969112
|
||||
├── prometheus-ecs-discovery -> /home/marchambault/.local/share/gitforgefs/github.com/187891900
|
||||
├── simplefuse -> /home/marchambault/.local/share/gitforgefs/github.com/111226611
|
||||
├── tmux-continuum -> /home/marchambault/.local/share/gitforgefs/github.com/160746043
|
||||
├── ttyd -> /home/marchambault/.local/share/gitforgefs/github.com/132514236
|
||||
├── usb-libvirt-hotplug -> /home/marchambault/.local/share/gitforgefs/github.com/128696299
|
||||
└── vfio-win10 -> /home/marchambault/.local/share/gitforgefs/github.com/388475049
|
||||
|
||||
696 directories, 0 files
|
||||
24 directories, 0 files
|
||||
```
|
||||
|
||||
## Supported forges
|
||||
|
||||
Currently, the following forges are supported:
|
||||
|
||||
| Forge | Name in configuration | API token permissions, if using an API key |
|
||||
| ------------------------------- | --------------------- | ------------------------------------------------------ |
|
||||
| [Gitlab](https://gitlab.com) | `gitlab` | `read_user`, `read_api` |
|
||||
| [Github](https://github.com) | `github` | `repo` |
|
||||
| [Gitea](https://gitea.com) | `gitea` | organization: `read`, repository: `read`, user: `read` |
|
||||
| [Forgejo](https://forgejo.org/) | `gitea` | organization: `read`, repository: `read`, user: `read` |
|
||||
|
||||
Merge requests to add support to other forges are welcome.
|
||||
|
||||
## Install
|
||||
|
||||
Install [go](https://golang.org/) and run
|
||||
``` sh
|
||||
go install github.com/badjware/gitlabfs@latest
|
||||
go install github.com/badjware/gitforgefs
|
||||
```
|
||||
|
||||
The executable will be in `$GOPATH/bin/gitlabfs` or `~/go/bin/gitlabfs` by default. For convenience, copy `gitlabfs` somewhere suitable or add `~/go/bin` in your `PATH`.
|
||||
The executable will be in `$GOPATH/bin/gitforgefs` or `~/go/bin/gitforgefs` by default. For convenience, add `~/go/bin` in your `$PATH` if not done already.
|
||||
|
||||
## Usage
|
||||
|
||||
Download the [example configuration file](./config.example.yaml) and edit the default configuration to suit your needs.
|
||||
|
||||
### Getting an API token
|
||||
|
||||
To generate an api token, log into your Gitlab instance, and go in your user settings > Access Token. Create a personal access token with the following permissions at the minimum:
|
||||
* `read_user`
|
||||
* `read_api`
|
||||
|
||||
### Getting the group ids
|
||||
|
||||
The group id can be seen just under the name of the group in Gitlab.
|
||||
|
||||
|
||||
|
||||
### Getting the user ids
|
||||
|
||||
Log into gitlab and go to https://gitlab.com/api/v4/users?username=USERNAME where `USERNAME` is the username of the user you wish to know the id of. The json response will contain the user id.
|
||||
|
||||
See https://forum.gitlab.com/t/where-is-my-user-id-in-gitlab-com/7912
|
||||
|
||||
### Mounting the filesystem
|
||||
|
||||
You can mount the filesystem with the following command:
|
||||
Then, you can run gitforgefs as follows:
|
||||
``` sh
|
||||
~/go/bin/gitlabfs -config /path/to/your/config.yaml /path/to/mountpoint
|
||||
gitforgefs -config config.yaml /path/to/mountpoint
|
||||
```
|
||||
Once the filesystem is mounted, you can `cd` into it and navigate it like any other filesystem. The first time `ls` is run the list of groups and projects is fetched from Gitlab. This operation can take a few seconds and the command will appear frozen until it's completed. Subsequent `ls` will fetch from the cache and should be much faster.
|
||||
|
||||
If `on_clone` is set to `init` or `no-checkout`, the locally cloned project will appear empty. Simply running `git pull` manually in the project folder will sync it up with Gitlab.
|
||||
|
||||
### Unmounting the filesystem
|
||||
|
||||
To stop the filesystem, use the command `umount /path/to/mountpoint` to cleanly unmount the filesystem.
|
||||
|
||||
If `gitlabfs` is not cleanly stopped, you might start seeing the error "transport endpoint is not connected" when trying to access the mountpoint, even preventing from mounting back the filesystem on the same mountpoint. To fix this, use `umount` as root user, eg: `sudo umount /path/to/mountpoint`.
|
||||
Stopping gitforgefs will unmount the filesystem. In the event the mountpoint is stuck in a bad state (eg: due to receiving a SIGKILL), you may need to manually cleanup using `umount`:
|
||||
``` sh
|
||||
sudo umount /path/to/mountpoint
|
||||
```
|
||||
|
||||
### Running automatically on user login
|
||||
|
||||
See [./contrib/systemd](contrib/systemd) for instructions on how to configure a systemd service to automatically run gitlabfs on user login.
|
||||
See [./contrib/systemd](contrib/systemd) for instructions on how to configure a systemd service to automatically run gitforgefs on user login.
|
||||
|
||||
## Caching
|
||||
|
||||
To reduce the number of calls to the Gitlab api and improve the responsiveness of the filesystem, `gitlabfs` will cache the content of the group in memory. If a group or project is renamed, created or deleted from Gitlab, these change will not appear in the filesystem. To force `gitlabfs` to refresh its cache, use `touch .refresh` in the folder to refresh to force `gitlabfs` to query Gitlab for the list of groups and projects again.
|
||||
### Filesystem cache
|
||||
|
||||
While the filesystem lives in memory, the git repositories that are cloned are saved on disk. By default, they are saved in `$XDG_DATA_HOME/gitlabfs` or `$HOME/.local/share/gitlabfs`, if `$XDG_DATA_HOME` is unset. `gitlabfs` symlink to the local clone of that repo. The local clone is unaffected by project rename or archive/unarchive in Gitlab and a given project will always point to the correct local folder.
|
||||
To reduce the number of calls to the APIs and improve the responsiveness of the filesystem, gitforgefs will cache the content of the forge in memory. If a group or project is renamed, created or deleted from the forge, these change will not appear in the filesystem immediately. To force gitforgefs to refresh its cache, use `touch .refresh` in the folder to signal gitforgefs to refresh this folder.
|
||||
|
||||
## Known issues / Future improvements
|
||||
* Cache persists forever until a manual refresh is requested. Some way to automatically refresh would be nice.
|
||||
* The filesystem is currently read-only. Implementing `mkdir` to create groups, `ln` or `touch` to create projects, etc. would be nice.
|
||||
* Code need some cleanup and could maybe be optimized here and there.
|
||||
### Local repository cache
|
||||
|
||||
## Building
|
||||
While the filesystem lives in memory, the git repositories that are cloned are saved on disk. By default, they are saved in `$XDG_DATA_HOME/gitforgefs` or `$HOME/.local/share/gitforgefs`, if `$XDG_DATA_HOME` is unset. `gitforgefs` symlink to the local clone of that repo. The local clone is unaffected by project rename or archive/unarchive in Gitlab and a given project will always point to the correct local folder.
|
||||
|
||||
## Future improvements
|
||||
* Cache persists forever until a manual refresh is requested. Some way to automatically refresh after a timeout would be nice.
|
||||
|
||||
## Building from the repo
|
||||
|
||||
Simply use `make` to create the executable. The executable will be in `bin/`.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,12 +1,15 @@
|
|||
This unit file allows you to automatically start gitlabfs as a systemd unit.
|
||||
This unit file allows you to automatically start gitforgefs as a systemd unit.
|
||||
|
||||
## Install
|
||||
1. Install gitlabfs using `go get`
|
||||
2. Run `which gitlabfs` to verify that gitlabfs is present in your PATH. if the command fail, you may need to add **$HOME/go/bin** to your PATH.
|
||||
3. Copy **gitlabfs@.service** into **~/.config/systemd/user**. Create the folder if it does not exists.
|
||||
4. Reload systemd: `systemctl --user daemon-reload`
|
||||
## Setup
|
||||
1. Install gitforgefs
|
||||
2. Copy **gitforgefs@.service** into **$HOME/.config/systemd/user**. Create the folder if it does not exists.
|
||||
``` sh
|
||||
mkdir -p $HOME/.config/systemd/user
|
||||
curl -o $HOME/.config/systemd/user/gitforgefs@.service https://raw.githubusercontent.com/badjware/gitlabfs/dev/contrib/systemd/gitforgefs%40.service
|
||||
```
|
||||
3. Reload systemd: `systemctl --user daemon-reload`
|
||||
|
||||
## Usage
|
||||
1. Create your gitlabfs config file in **~/.config/gitlabfs** eg: **~/.config/gitlabfs/gitlab.com.yaml**. Make sure the config file name ends with **.yaml** and a mountpoint is configured in the file.
|
||||
2. Start your service with `systemctl --user start gitlabfs@<name of your config>.service`. eg: `systemctl --user start gitlabfs@gitlab.com.service`. Omit the **.yaml** in the name of the service.
|
||||
3. Enable your service start on login with `systemctl --user enable gitlabfs@<name of your config>.service`. eg: `systemctl --user enable gitlabfs@gitlab.com.service`
|
||||
1. Create your gitforgefs config file in **$HOME/.config/gitforgefs** eg: **$HOME/.config/gitforgefs/gitlab.com.yaml**. Make sure the config file name ends with **.yaml** and a mountpoint is configured in the file.
|
||||
2. Start your service with `systemctl --user start gitforgefs@<name of your config>.service`. eg: `systemctl --user start gitforgefs@gitlab.com.service`. Omit the **.yaml** extension.
|
||||
3. Enable your service to start on login with `systemctl --user enable gitforgefs@<name of your config>.service`. eg: `systemctl --user enable gitforgefs@gitlab.com.service`
|
||||
|
|
|
|||
Loading…
Reference in New Issue