linuxfoo-gitlab/README.md

# linuxfoo-gitlab

## Summary

Embed a list of the most recent commits to a Gitlab project. Information is retrieved from a specified Gitlab instance's public REST API.

## Shortcode `gitlab-show-project`

### Examples

Add the following shortcode for a list of at most 5 commits to that project that were made since at most 3 months ago:

```
[gitlab-show-project url="https://tk-sls.de/gitlab" project_id=42 since="3 months" max=5]
```

Add the following shortcode for a list of at most 3 commits followed by a link to the latest release:

```
[gitlab-show-project url="https://tk-sls.de/gitlab" project_id=42 max=3 releases="latest"]
```

Add the following shortcode to just link to the Gitlab project, without a list of commits or releases:

```
[gitlab-show-project url="https://tk-sls.de/gitlab" project_id=42 commit="none" releases="none"]
```

### Attributes

The following attributes are mandatory:

* `url="STRING"`: Base URL of Gitlab instance (example: `https://tk-sls.de/gitlab`).
* `project_id=NUM`: ; `NUM`: Positive Integer, valid project ID in Gitlab specified by `url` (example: `42`).

The following optional attributes enable or disable additional project information:

* `commits="STRING"`: Optional; if set, `STRING` can be either `all` (show a list of recent commits, the default) or `none` (do not show a list of recent commits).
* `releases=STRING`: Optional; if set, `STRING` can be either `all` (show a list of all releases of this project, if any) or `latest` (show a link to the latest release of this project, if any) or `none` (do not show releases of this project, the default).

The following optional attributes modify the behavior of the list of commits:

* `since="NUM UNIT"`: Optional; `NUM`: Positive integer; `UNIT`: `days`, `months`, `years`; exclude commits older than specified time interval (example: `3 months`).
* `max=NUM`: Optional; `NUM`: Positive integer; list not more than `NUM` commits (example: `5`).
* `ref_name=STRING`: Optional: list only commit from branch or reference name `STRING` (examples: `main`, `v1.1`).
* `default_branch`: Optional; if set, list only commits from the project's default branch.
* `author="none"`: Optional; do not print names of authors in the commit list.

## Author and License

* Copyleft 2021 Tilman Kranz <[t.kranz@tk-sls.de](mailto:t.kranz@tk-sls.de)>  
* License: MIT License [https://opensource.org/licenses/MIT](https://opensource.org/licenses/MIT)