This shows you the differences between two versions of the page.
Next revision | Previous revision | ||
userdoc:cgit-meta-data [2018-04-02 18:07] mricon created |
userdoc:cgit-meta-data [2020-05-08 14:02] (current) mricon |
||
---|---|---|---|
Line 1: | Line 1: | ||
+ | ~~REDIRECT>https://korg.docs.kernel.org/cgit-meta-data.html~~ | ||
+ | |||
====== Repo appearance on git.kernel.org ====== | ====== Repo appearance on git.kernel.org ====== | ||
- | You can change how your repository is shown on git.kernel.org using a special __meta__ branch of each repository. | + | You can change how your repository is shown on git.kernel.org using a special ''refs/meta/cgit'' ref in each repository. |
- | ===== Creating the __meta__ branch ===== | + | ===== Creating the special ref ===== |
- | To create the special __meta__ branch, use the following commands: | + | To create the special ''refs/meta/cgit'' ref, use the following commands: |
<code> | <code> | ||
- | git checkout --orphan __meta__ | + | git symbolic-ref HEAD refs/meta/cgit |
- | git rm -rf . | + | git reset --hard |
- | # add any files you need, see below | + | # add and commit any files you need, see below |
- | git push origin __meta__ | + | git push origin HEAD:refs/meta/cgit |
+ | git checkout master | ||
</code> | </code> | ||
- | ===== Cgit configuration options ===== | + | ===== Editing files in the special ref ===== |
- | You can now add a cgitrc file to the __meta__ branch, for example: | + | It is a bit trickier to edit files in the special ref as opposed to a normal branch. |
<code> | <code> | ||
+ | git fetch origin refs/meta/cgit | ||
+ | git checkout FETCH_HEAD | ||
+ | # make any changes and commit them | ||
+ | git push origin HEAD:refs/meta/cgit | ||
+ | git checkout master | ||
+ | </code> | ||
+ | |||
+ | ===== Cgit configuration options ===== | ||
+ | |||
+ | You can add a ''cgitrc'' file to the ''refs/meta/cgit'' location, for example: | ||
+ | |||
+ | <file> | ||
owner=Tux Penguino | owner=Tux Penguino | ||
desc=Frobble module development | desc=Frobble module development | ||
- | </code> | + | </file> |
- | Almost all repo.* configuration parameters are supported -- for more details, see [[https://git.zx2c4.com/cgit/tree/cgitrc.5.txt|man cgitrc]]. For security reasons, some sensitive parameters like url, path, filters, etc will be ignored. | + | Many ''repo.*'' configuration parameters are supported (see allowlist below). For in-depth description of each option, see [[https://git.zx2c4.com/cgit/tree/cgitrc.5.txt|man cgitrc]]. |
- | Other useful configuration options: | + | Full list of allowed options (make sure there are no spaces around ''=''): |
- | <code> | + | <file> |
- | # turn off .tar.gz snapshots for your repository | + | # repository owner (e.g. your name) |
+ | owner=Tux Penguino | ||
+ | # repository description | ||
+ | desc=Frobble module development | ||
+ | # generate tarballs with this prefix instead of repo name | ||
+ | # e.g. instead of linux-stable-x.x.x.tar.gz, do linux-x.x.x.tar.gz | ||
+ | snapshot-prefix=linux | ||
+ | # Link to the project home page | ||
+ | homepage=https://frobblemod.io | ||
+ | # Default branch to show, if it's not master | ||
+ | defbranch=frobble | ||
+ | # turn off .tar.gz snapshots for this repository | ||
snapshots=0 | snapshots=0 | ||
# hide the repository from the listing, but leave it accessible via direct link | # hide the repository from the listing, but leave it accessible via direct link | ||
Line 34: | Line 60: | ||
# don't make this repository accessible via cgit (but make it still clonable) | # don't make this repository accessible via cgit (but make it still clonable) | ||
ignore=1 | ignore=1 | ||
- | </code> | + | </file> |
- | :!: Note, that ''ignore=1'' still allows that repository to be cloned via ''git://'' or ''https://'' if someone knows the full path to it. | + | :!: Note, that ''ignore=1'' still allows that repository to be cloned via ''git:'' or ''https:'' endpoints if someone knows the full path to it. |
===== Repo-specific about tab ===== | ===== Repo-specific about tab ===== | ||
- | Your repository is probably going to be a clone of linux.git, so if you want to display different info in the "about" tab of the repo instead of the default linux README, you can add a separate README file in the __meta__ branch. | + | Your repository is probably going to be a clone of linux.git, so if you want to display different info in the "about" tab of the repo instead of the default linux README, you can add a separate README file in the ''refs/meta/cgit'' location. |
We will look for README, README.md and README.rst files, so if you want Markdown or ReST formatting in the about tab, you can use the appropriate file extension. | We will look for README, README.md and README.rst files, so if you want Markdown or ReST formatting in the about tab, you can use the appropriate file extension. | ||
Line 46: | Line 72: | ||
===== Note on caching ===== | ===== Note on caching ===== | ||
- | CGit heavily relies on caching, so it can take up to a few hours for the changes you made to the __meta__ branch to show up on git.kernel.org. | + | CGit heavily relies on caching, so it can take up to a few hours for the changes you made to the ''refs/meta/cgit'' ref to show up on git.kernel.org. |