GIT-OBS(1)

NAME
git-obs - Git based command-line client for Open Build Service

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 ~/.config/tea/config.yml.

-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

AUTHOR
Contributors to the osc project. See the project's GIT history for the complete list.

DISTRIBUTION
The latest version of osc may be downloaded from https://github.com/openSUSE/osc/