git-obs(1)
| GIT-OBS(1) | Generated Python Manual | GIT-OBS(1) |
NAME
git-obs
SYNOPSIS
git-obs [global opts] <command> [--help] [opts] [args]
DESCRIPTION
git-obs is a command-line client for interacting with Git repositories within a Gitea instance that is part of an Open Build Service (OBS).
OPTIONS
- -q, --quiet
- Mute unnecessary output
- --gitea-config GITEA_CONFIG
- Path to gitea config. Default: $GIT_OBS_CONFIG or $XDG_CONFIG_HOME/tea/config.yml (~/.config/tea/config.yml when XDG_CONFIG_HOME is unset or empty).
- -G GITEA_LOGIN, --gitea-login GITEA_LOGIN
- Name of the login entry in the config file. Default: $GIT_OBS_LOGIN or the
default entry from the config file. Alternatively, you can use gitea url
as long as there's only a single matching entry in the config file.
You can omit this argument and set GIT_OBS_GITEA_URL, GIT_OBS_GITEA_USER, and GIT_OBS_GITEA_TOKEN environmental variables instead. Optional variables: GIT_OBS_GITEA_SSH_KEY
To override the existing values from the config file, you can specify the following environmental variables:
- GIT_OBS_LOGIN_<LOGIN-NAME>_USER
- GIT_OBS_LOGIN_<LOGIN-NAME>_TOKEN
- GIT_OBS_LOGIN_<LOGIN-NAME>_SSH_KEY Setting new ``name`` or ``url`` is not possible. Please note that the login name that is part of the environmental variable name is case sensitive.
COMMANDS
git-obs api
Make an arbitrary request to API
usage: git-obs [global opts] api [-h] [-X
{GET,HEAD,POST,PATCH,PUT,DELETE}]
[--data DATA]
url
arguments:
- url
options:
- -X {GET,HEAD,POST,PATCH,PUT,DELETE}, --method {GET,HEAD,POST,PATCH,PUT,DELETE}
- --data DATA
git-obs file
Manage metadata files in a repo
usage: git-obs [global opts] file [-h] {maintainership} ...
git-obs file maintainership
Manage the _maintainership.json file
usage: git-obs [global opts] maintainership [-h] {migrate} ...
git-obs file maintainership migrate
Read _maintainership.json and convert it from legacy format to the current format
usage: git-obs [global opts] migrate [-h] [-i] [path]
arguments:
- path
- Path to the _maintainership.json file (default: _maintainership.json)
options:
- -i, --in-place
- Write the result back to the original file instead of printing to stdout
git-obs login
Manage configured credentials to Gitea servers
usage: git-obs [global opts] login [-h]
{add,gitcredentials-helper,list,remove,update} ...
git-obs login add
Add a Gitea credentials entry
usage: git-obs [global opts] add [-h] --url URL --user USER
[--token TOKEN]
[--ssh-key PATH] [--ssh-agent]
[--ssh-key-agent-pub SSH_KEY_AGENT_PUB]
[--git-uses-http] [--quiet]
[--set-as-default]
name
arguments:
- name
- The name of the login entry to be added
options:
- --url URL
- Gitea URL, for example https://example.com
- --user USER
- Gitea username
- --token TOKEN
- Gitea access token; omit or set to '-' to invoke a secure interactive prompt
- --ssh-key PATH
- Path to a private SSH key
- --ssh-agent
- Use ssh-agent for authentication
- --ssh-key-agent-pub SSH_KEY_AGENT_PUB
- Public SSH key signature for ssh authentication. Setting this option switches from token to ssh auth.
- --git-uses-http
- Git uses http(s) instead of SSH
- --quiet
- Mute unnecessary output when using this login entry
- --set-as-default
- Set the new login entry as default
git-obs login list
List Gitea credentials entries
usage: git-obs [global opts] list [-h] [--show-tokens]
options:
- --show-tokens
- Show tokens in the output
git-obs login remove
Remove a Gitea credentials entry
usage: git-obs [global opts] remove [-h] name
arguments:
- name
- The name of the login entry to be removed
git-obs login update
Update a Gitea credentials entry
usage: git-obs [global opts] update [-h] [--new-name NEW_NAME]
[--new-url URL]
[--new-user USER] [--new-token TOKEN]
[--new-ssh-key PATH]
[--new-ssh-agent {0,1,yes,no}]
[--new-ssh-key-agent-pub NEW_SSH_KEY_AGENT_PUB]
[--new-git-uses-http {0,1,yes,no}]
[--new-quiet {0,1,yes,no}]
[--set-as-default]
name
arguments:
- name
- The name of the login entry to be updated
options:
- --new-name NEW_NAME
- New name of the login entry
- --new-url URL
- New Gitea URL, for example https://example.com
- --new-user USER
- Gitea username
- --new-token TOKEN
- Gitea access token; set to '-' to invoke a secure interactive prompt
- --new-ssh-key PATH
- Path to a private SSH key
- --new-ssh-agent {0,1,yes,no}
- Use ssh-agent for authentication
- --new-ssh-key-agent-pub NEW_SSH_KEY_AGENT_PUB
- Public SSH key signature for ssh authentication. Setting this option switches from token to ssh auth.
- --new-git-uses-http {0,1,yes,no}
- Git uses http(s) instead of SSH
- --new-quiet {0,1,yes,no}
- Mute unnecessary output when using this login entry
- --set-as-default
- Set the login entry as default
git-obs meta
Manage metadata in .git/obs store
usage: git-obs [global opts] meta [-h] {info,list,pull,reset,set} ...
git-obs meta info
Resolve and print metadata about the current checkout
usage: git-obs [global opts] info [-h] [--type | --apiurl |
--project |
--package | --branch | --commit | --remote |
--remote-url | --export]
options:
- --type
- Print type
- --apiurl
- Print apiurl
- --project
- Print project
- --package
- Print package
- --branch
- Print branch
- --commit
- Print commit
- --remote
- Print remote
- --remote-url
- Print remote_url
- --export
- Show json objects instead of human readable text
git-obs meta list
List metadata in store
usage: git-obs [global opts] list [-h] [--branch BRANCH]
options:
- --branch BRANCH
- Manage values for the specified branch (default: current branch)
git-obs meta pull
Pull metadata about the project or package from Gitea.
usage: git-obs [global opts] pull [-h]
git-obs meta reset
Reset metadata in store
usage: git-obs [global opts] reset [-h] [--branch BRANCH]
options:
- --branch BRANCH
- Manage values for the specified branch (default: current branch)
git-obs meta set
Set metadata in store
usage: git-obs [global opts] set [-h] [--apiurl APIURL] [--project
PROJECT]
[--package PACKAGE] [--branch BRANCH]
options:
- --apiurl APIURL
- Set 'apiurl'
- --project PROJECT
- Set 'project'
- --package PACKAGE
- Set 'package'
- --branch BRANCH
- Manage values for the specified branch (default: current branch)
git-obs pr
Manage pull requests
usage: git-obs [global opts] pr [-h]
{cancel-scheduled-merge,checkout,close,comment,create,dump,forward,get,show,list,merge,new-package-request,reopen,review,search,set,show-patch}
...
git-obs pr cancel-scheduled-merge
Cancel scheduled merge of pull requests
usage: git-obs [global opts] cancel-scheduled-merge [-h] id [id ...]
arguments:
- id
- Pull request ID in <owner>/<repo>#<number> format
git-obs pr checkout
Check out a pull request
usage: git-obs [global opts] checkout [-h] [-f] pull
arguments:
- pull
- Number of the pull request
options:
- -f, --force
- Reset the existing local branch to the latest state of the pull request
git-obs pr close
Close pull requests
usage: git-obs [global opts] close [-h] [-m MESSAGE] id [id ...]
arguments:
- id
- Pull request ID in <owner>/<repo>#<number> format
options:
- -m MESSAGE, --message MESSAGE
- Text of the comment
git-obs pr comment
Comment pull requests
usage: git-obs [global opts] comment [-h] [-m MESSAGE] id [id ...]
arguments:
- id
- Pull request ID in <owner>/<repo>#<number> format
options:
- -m MESSAGE, --message MESSAGE
- Text of the comment
git-obs pr create
Create a pull request
usage: git-obs [global opts] create [-h] [--title TEXT]
[--description TEXT]
[--source BRANCH_ID] [--target BRANCH_ID]
[--source-owner OWNER]
[--source-repo REPO]
[--source-branch BRANCH]
[--target-owner OWNER]
[--target-repo REPO]
[--target-branch BRANCH] [--self]
[--separate-requests] [--dry-run]
[--allow-empty]
[--allow-maintainer-edit {0,1,yes,no}]
options:
- --title TEXT
- Pull request title
- --description TEXT
- Pull request description (body)
- --source BRANCH_ID
- Source owner, repo and branch (format: <owner>/<repo>:<branch>)
- --target BRANCH_ID
- Target owner, repo and branch (format: <owner>/<repo>:<branch>, <owner>:<branch>, :<branch>)
- --self
- Use the local git repository as the target for the pull request
- --separate-requests
- Create separate pull requests for each package in the project
- --dry-run
- Do not actually create the pull request
- --allow-empty
- Allow creating a pull request even if there are no changes
- --allow-maintainer-edit {0,1,yes,no}
- Whether users with write access to the base branch can also push to the pull request's head branch (default: yes)
deprecated options
- --source-owner OWNER
- Owner of the source repo (deprecated, use --source instead)
- --source-repo REPO
- Name of the source repo (deprecated, use --source instead)
- --source-branch BRANCH
- Source branch (deprecated, use --source instead)
- --target-owner OWNER
- Target owner (deprecated, use --target instead)
- --target-repo REPO
- Target repo (deprecated, use --target instead)
- --target-branch BRANCH
- Target branch (deprecated, use --target instead)
git-obs pr dump
Dump a pull request to disk
usage: git-obs [global opts] dump [-h] [--subdir-fmt FMT] id [id ...]
Return codes: - 0: default return code - 1-9: reserved for error states - 11: pull request(s) skipped due to no longer being open
In addition to the return codes, a STATUS file is written in each target directory, the values are: RUNNING, FAILED, SUCCESS
arguments:
- id
- Pull request ID in <owner>/<repo>#<number> format
options:
- --subdir-fmt FMT
- Formatting string for a subdir associated with each pull request (default:
'{owner}/{repo}/{number}') Available values:
- 'owner', 'repo' and 'number' parsed from the specified pull request ID
- 'pr' object which is an instance of 'osc.gitea_api.PullRequest'
- 'login_name', 'login_user' from the currently used Gitea login entry
git-obs pr forward
Forward sources from one branch to another (Fork -> Sync -> Push -> PR)
usage: git-obs [global opts] forward [-h] [--workdir WORKDIR]
[--no-cleanup]
[--dry-run] [--source-url SOURCE_URL]
[--title TITLE]
[--description DESCRIPTION] [-e]
--mode {merge,merge-unrelated,fast-forward,sync,auto}
owner_repo source_branch target_branch
arguments:
- owner_repo
- Owner and repo: (format: <owner>/<repo>)
- source_branch
- Source branch name (e.g. factory)
- target_branch
- Target branch name (e.g. slfo-main)
options:
- --workdir WORKDIR
- Working directory for git operations (default: temporary directory)
- --no-cleanup
- Do not remove the temporary directory after completion
- --dry-run
- Do not actually create the pull request or push changes
- --source-url SOURCE_URL
- URL of the source git repository (if different from upstream)
- --title TITLE
- Pull request title
- --description DESCRIPTION
- Pull request description (body)
- -e, --edit
- Open an editor to edit the pull request title and description.
- --mode {merge,merge-unrelated,fast-forward,sync,auto}
- merge: Merge the source branch into the target branch, remove any extra files not found in the target. merge-unrelated: Same as merge, but with merging unrelated histories allowed. Consider using other modes first. fast-forward: Fast-forward changes, don't create any merge commit. sync: Create a new commit that synchronizes the contents of the branch with the source branch. auto: Use fast-forward if possible, merge otherwise.
git-obs pr get (show)
Get details about the specified pull requests
usage: git-obs [global opts] get [-h] [-p] [--timeline]
owner_repo_pull [owner_repo_pull ...]
arguments:
- owner_repo_pull
- Owner, repo and pull request number (format: <owner>/<repo>#<pull-request-number>)
options:
- -p, --patch
- Show patches associated with the pull requests
- --timeline
- Show timelines of the pull requests
git-obs pr list
List pull requests in a repository
usage: git-obs [global opts] list [-h] [--state {open,closed,all}]
[--reviewer REVIEWERS]
[--review-state {REQUEST_REVIEW,APPROVED}]
[--target-branch TARGET_BRANCHES]
[--source-owner SOURCE_OWNERS] [--no-draft]
[--label LABELS] [--export]
owner_repo [owner_repo ...]
arguments:
- owner_repo
- Owner and repo: (format: <owner>/<repo>)
options:
- --state {open,closed,all}
- State of the pull requests (default: open)
- --reviewer REVIEWERS
- Filter by reviewer. Team reviewers start with '@'.
- --review-state {REQUEST_REVIEW,APPROVED}
- Filter by review state. Needs to be used with ``--reviewer``.
- --target-branch TARGET_BRANCHES
- Filter by target branch.
- --source-owner SOURCE_OWNERS
- Filter by source owner.
- --no-draft
- Filter by draft flag. Exclude pull requests with draft flag set.
- --label LABELS
- Filter by label. Can be specified multiple times.
- --export
- Show json objects instead of human readable text
git-obs pr merge
Merge pull requests
usage: git-obs [global opts] merge [-h] [--now] id [id ...]
arguments:
- id
- Pull request ID in <owner>/<repo>#<number> format
options:
- --now
- Merge immediately, don't wait until all checks succeed.
git-obs pr new-package-request
Request a new package
usage: git-obs [global opts] new-package-request [-h] [-m MESSAGE]
-t TARGET
[packages ...]
Create a new package request issue in the target repository.
arguments:
- packages
- Package(s) to add (format: <owner>/<repo>:<branch>). If omitted, the current checkout is used. Specify the most significant packages first. (format: <owner>/<repo>:<branch>)
options:
- -m MESSAGE, --message MESSAGE
- Additional information (e.g., links to bug trackers) that justify adding the package(s).
- -t TARGET, --target TARGET
- Target repository and branch (format: <owner>/<repo>:<branch>) (format: <owner>/<repo>:<branch>)
git-obs pr reopen
Reopen pull requests
usage: git-obs [global opts] reopen [-h] [-m MESSAGE] id [id ...]
arguments:
- id
- Pull request ID in <owner>/<repo>#<number> format
options:
- -m MESSAGE, --message MESSAGE
- Text of the comment
git-obs pr review
Manage pull request reviews
usage: git-obs [global opts] review [-h]
{approve,cancel-request,decline,interactive} ...
git-obs pr review approve
Approve pull request reviews
usage: git-obs [global opts] approve [-h] [-m MESSAGE] [--commit
COMMIT]
[--reviewer REVIEWER]
id [id ...]
arguments:
- id
- Pull request ID in <owner>/<repo>#<number> format
options:
- -m MESSAGE, --message MESSAGE
- Justification of the review state change
- --commit COMMIT
- Pin the review to the specified commit
- --reviewer REVIEWER
- Review on behalf of the specified reviewer that is associated to group review bot
git-obs pr review cancel-request
Cancel a request for review of pull request
usage: git-obs [global opts] cancel-request [-h] [-n] [-a] [-x
EXCLUDE]
owner_repo_pull [user ...]
arguments:
- owner_repo_pull
- Owner, repo and pull request number (format: <owner>/<repo>#<pull-request-number>)
- user
- User with pending review request
options:
- -n, --dry-run
- Don't do any action, only report what should be done
- -a, --all
- Cancel all pending review requests
- -x EXCLUDE, --exclude EXCLUDE
- Users to ignore when cancelling review requests.
git-obs pr review decline
Decline pull request reviews (request changes)
usage: git-obs [global opts] decline [-h] -m MESSAGE [--commit
COMMIT]
[--reviewer REVIEWER]
id [id ...]
arguments:
- id
- Pull request ID in <owner>/<repo>#<number> format
options:
- -m MESSAGE, --message MESSAGE
- Justification of the review state change
- --commit COMMIT
- Pin the review to the specified commit
- --reviewer REVIEWER
- Review on behalf of the specified reviewer that is associated to group review bot
git-obs pr review interactive
Interactive review of pull requests
usage: git-obs [global opts] interactive [-h] [--reviewer REVIEWER] [id ...]
Since this is an interactive command, the program return code indicates the user choice: - 0: default return code - 1-9: reserved for error states - 10: user selected "exit" - 11: user selected "skip"
This might be useful when wrapping the command in any external review tooling, handling one review at a time.
arguments:
- id
- Pull request ID in <owner>/<repo>#<number> format
options:
- --reviewer REVIEWER
- Review on behalf of the specified reviewer that is associated to group review bot
git-obs pr search
Search pull requests in the whole gitea instance
usage: git-obs [global opts] search [-h] [--state {open,closed}]
[--title TITLE] [--owner OWNER]
[--label LABEL] [--assigned] [--created]
[--mentioned] [--review-requested]
[--export]
options:
- --state {open,closed}
- Filter by state: open, closed (default: open)
- --title TITLE
- Filter by substring in title
- --owner OWNER
- Filter by owner of the repository associated with the pull requests
- --label LABEL
- Filter by associated labels. Non existent labels are discarded. Can be specified multiple times.
- --assigned
- Filter pull requests assigned to you
- --created
- Filter pull requests created by you
- --mentioned
- Filter pull requests mentioning you
- --review-requested
- Filter pull requests requesting your review
- --export
- Show json objects instead of human readable text
git-obs pr set
Change a pull request
usage: git-obs [global opts] set [-h] [--title TITLE]
[--description DESCRIPTION]
[--allow-maintainer-edit ALLOW_MAINTAINER_EDIT]
owner_repo_pull [owner_repo_pull ...]
arguments:
- owner_repo_pull
- Owner, repo and pull request number (format: <owner>/<repo>#<pull-request-number>)
options:
- --title TITLE
- --description DESCRIPTION
- --allow-maintainer-edit ALLOW_MAINTAINER_EDIT
- Users with write access to the base branch can also push to the pull request's head branch
git-obs pr show-patch
Show patch associated to the specified pull request
usage: git-obs [global opts] show-patch [-h] owner_repo_pull
arguments:
- owner_repo_pull
- Owner, repo and pull request number (format: <owner>/<repo>#<pull-request-number>)
git-obs repo
Manage git repos
usage: git-obs [global opts] repo [-h] {clone,fork,init,list} ...
git-obs repo clone
Clone a git repo
usage: git-obs [global opts] clone [-h] [-b BRANCH] [-a] [-i
SSH_KEY]
[--no-ssh-strict-host-key-checking]
[--directory DIRECTORY]
owner_repo [owner_repo ...]
NOTE: Some of the options may result in setting "core.sshCommand" config option in the git repository."
arguments:
- owner_repo
- Owner and repo: (format: <owner>/<repo>)
options:
- -b BRANCH, --branch BRANCH
- Checkout the specified branch
- -a, --anonymous
- Clone anonymously via the http protocol
- -i SSH_KEY, --ssh-key SSH_KEY
- Path to a private SSH key (identity file)
- --no-ssh-strict-host-key-checking
- Set 'StrictHostKeyChecking no' ssh option
- --directory DIRECTORY
- Clone into the given directory
git-obs repo fork
Fork a git repo
usage: git-obs [global opts] fork [-h] [--new-repo-name
NEW_REPO_NAME]
[--target-owner OWNER]
owner_repo [owner_repo ...]
arguments:
- owner_repo
- Owner and repo: (format: <owner>/<repo>)
options:
- --new-repo-name NEW_REPO_NAME
- Name of the newly forked repo
- --target-owner OWNER
- Target owner (default: user's organization)
git-obs repo init
Init a git repo
usage: git-obs [global opts] init [-h] [-a] [-t TEMPLATE] [-i
SSH_KEY]
[--no-ssh-strict-host-key-checking]
path
Initialize or update a package git repo, setting .gitignore, .gitattributes and other files from a template.
arguments:
- path
- Destination path to a directory which needs to be initialized. Default is current working directory
options:
- -a, --anonymous
- Clone anonymously via the http protocol
- -t TEMPLATE, --template TEMPLATE
- Path to a template directory url to git repository
- -i SSH_KEY, --ssh-key SSH_KEY
- Path to a private SSH key (identity file)
- --no-ssh-strict-host-key-checking
- Set 'StrictHostKeyChecking no' ssh option
git-obs repo list
List repos
usage: git-obs [global opts] list [-h] [--org ORG_LIST] [--user
USER_LIST]
[--export]
Required permissions:
read:organization
read:user
options:
- --org ORG_LIST
- List repos owned by the specified organizations
- --user USER_LIST
- List repos owned by the specified users
- --export
- Show json objects instead of human readable text
git-obs ssh-key
Manage public SSH keys
usage: git-obs [global opts] ssh-key [-h] {add,list,remove} ...
git-obs ssh-key add
usage: git-obs [global opts] add [-h] (--key KEY | --key-path PATH)
options:
- --key KEY
- SSH public key
- --key-path PATH
- Path to the SSH public key
git-obs ssh-key list
usage: git-obs [global opts] list [-h]
git-obs ssh-key remove
usage: git-obs [global opts] remove [-h] id
arguments:
- id
- Id of the SSH public key
git-obs staging
Manage staging projects
usage: git-obs [global opts] staging [-h] {group,remove,search} ...
git-obs staging group
Group multiple staging project pull requests into a target staging project pull request
usage: git-obs [global opts] group [-h] [--target TARGET] [--title
TITLE]
[--fork-owner FORK_OWNER]
[--fork-branch FORK_BRANCH]
[--remove-pr-references] [--force]
[--target-repo TARGET_REPO]
[--source-owner SOURCE_OWNER]
[--no-ssh-strict-host-key-checking]
[--cache-dir CACHE_DIR]
[pr_id ...]
arguments:
- pr_id
- List of project pull request to be merged into the target project pull request (format: <owner>/<repo>#<pull-request-number>)
options:
- --target TARGET
- Target project pull request to modify (format: <owner>/<repo>#<pull-request-number>). If not specified, a new pull request will be created.
- --title TITLE
- Title of the new pull request. Defaults to 'Update packages: <pkg> [pkg] ...'. Conflicts with --target.
- --fork-owner FORK_OWNER
- Owner of the fork used to create a new pull request. Defaults to the currently logged user. Conflicts with --target.
- --fork-branch FORK_BRANCH
- Branch in the fork used to create a new pull request. Defaults to 'for/<target_branch>/group-YYYY-MM-DD_HH-MM-SS'. Conflicts with --target.
- --remove-pr-references
- Remove 'PR:' references from the source project pull requests
- --force
- Allow force-push to the branch associated with the pull request
- --target-repo TARGET_REPO
- Target repo (format: <owner>/<repo>). Requires --source-owner.
- --source-owner SOURCE_OWNER
- Source owner (e.g. a devel project)
- --no-ssh-strict-host-key-checking
- Set 'StrictHostKeyChecking no' ssh option
- --cache-dir CACHE_DIR
- Path to a git cache.
git-obs staging remove
Remove package pull requests from a project pull request
usage: git-obs [global opts] remove [-h] [--close-removed]
[--keep-temp-dir]
target pr_id [pr_id ...]
arguments:
- target
- Project pull request to modify (format: <owner>/<repo>#<pull-request-number>)
- pr_id
- List of package pull requests to be removed from the project pull request (format: <owner>/<repo>#<pull-request-number>)
options:
- --close-removed
- Close pull requests after removing their references
- --keep-temp-dir
- Don't delete the temporary directory with git checkouts
git-obs staging search
Search staging pull requests.
usage: git-obs [global opts] search [-h] --type
{BACKLOG,INPROGRESS,ONHOLD}
[--package-review-state {APPROVED,ALL}]
[--target-branch TARGET_BRANCHES]
[--export]
owner_repo
arguments:
- owner_repo
- Owner and repo: (format: <owner>/<repo>)
options:
- --type {BACKLOG,INPROGRESS,ONHOLD}
- Filter by review state.
- --package-review-state {APPROVED,ALL}
- Filter by review state on *all* referenced *package* PRs.
- --target-branch TARGET_BRANCHES
- Filter by target branch.
- --export
- Show json objects instead of human readable text
DISTRIBUTION
The latest version of osc may be downloaded from https://github.com/openSUSE/osc/
| 2026-10-14 | osc |