Command Reference: `pr`

cml pr create [options] <pathspec>...

Commit specified files to a new branch and create a pull request. If sending a report afterwards, consider using cml comment update --pr.

Pull requests created with cml pr won't trigger a new CI/CD run, thereby preventing an infinite chain of runs. In some cases, the --skip-ci flag may be required (e.g. to stop GitLab CI running after --merge).

Files to commit can be specified using any syntax supported by Git pathspec.

Options

Any generic option in addition to:

--merge, --rebase, or --squash: Try to merge, rebase, or squash-merge the created PR after CI tests pass.
--md: Produce output in Markdown format ([CML Pull/Merge Request](url) instead of url).
--skip-ci: Prevent the PR/MR from triggering another CI run post-merge.
--remote=<name or URL>: Git remote name or URL [default: origin].
--user-email=<address>: Git user email for commits [default: olivaw@iterative.ai].
--user-name=<...>: Git user name for commits [default: Olivaw[bot]].
--branch: Pull request branch name [default: auto-generated].
--title: Pull request title [default: auto-generated].
--body: Pull request description [default: auto-generated].
--message: Commit message [default: auto-generated].

Examples

Commit all files in current working directory

$ cml pr create .

Automatically merge pull requests

$ date > output.txt
$ cml pr create --merge output.txt  # or --squash/--rebase

The --merge, --rebase, and --squash options enable auto–merge (GitHub) or merge when pipeline succeeds (GitLab) to merge the pull request as soon as checks succeed. If waiting for checks isn't supported, cml pr will try to merge the pull request immediately.

Command internals

$ cml pr create "**/*.py" "**/*.json"

is roughly equivalent to:

SHA="$(git log -n1 --format=%h)"
BASE="$(git branch)"

git checkout "${BASE}-cml-pr-${SHA}"

if [[ $(git ls-remote --exit-code origin\
        "${BASE}-cml-pr-${SHA}" &>/dev/null) ]]; then
  # branch already exists; just print its PR URL
  curl \
    -H "Accept: application/vnd.github.v3+json" \
    https://api.github.com/repos/${GITHUB_REPOSITORY}/pulls \
    | jq -r ".[] | select(.head.ref == '${BASE}-cml-pr-${SHA}') | .url"
else
  # create branch & PR
  git checkout -b "${BASE}-cml-pr-${SHA}"
  git add "**/*.py" "**/*.json"
  git commit -m "CML PR for ${SHA} [skip ci]"
  git push
  curl \
    -X POST \
    -H "Accept: application/vnd.github.v3+json" \
    https://api.github.com/repos/${GITHUB_REPOSITORY}/pulls \
    -d "{
      \"head\": \"${BASE}-cml-pr-${SHA}\",
      \"base\": \"${BASE}\",
      \"title\": \"CML PR for ${BASE} ${SHA}\",
      \"description\":
        \"Automated commits for\
          ${GITHUB_REPOSITORY}/commit/${SHA} created by CML.\"
    }" \
    | jq -r .url
fi

Command Reference: pr