{"id":15062986,"url":"https://github.com/cqse/teamscale-cli","last_synced_at":"2025-10-31T17:30:32.333Z","repository":{"id":47411202,"uuid":"95903606","full_name":"cqse/teamscale-cli","owner":"cqse","description":"A Teamscale command line interface to integrate findings into text editors such as vim, emacs or sublime.","archived":true,"fork":false,"pushed_at":"2024-02-20T06:57:03.000Z","size":1629,"stargazers_count":8,"open_issues_count":6,"forks_count":6,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-01-19T14:07:20.156Z","etag":null,"topics":["command-line-tool","emacs","software-quality","sublime","teamscale","vim"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cqse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-06-30T15:57:00.000Z","updated_at":"2024-11-12T08:39:15.000Z","dependencies_parsed_at":"2024-02-20T07:51:49.408Z","dependency_job_id":null,"html_url":"https://github.com/cqse/teamscale-cli","commit_stats":{"total_commits":167,"total_committers":19,"mean_commits":8.789473684210526,"dds":0.7125748502994012,"last_synced_commit":"aba16365ed738d4fc7555594ccb3588bc1d2af53"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cqse%2Fteamscale-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cqse%2Fteamscale-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cqse%2Fteamscale-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cqse%2Fteamscale-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cqse","download_url":"https://codeload.github.com/cqse/teamscale-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239221264,"owners_count":19602378,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["command-line-tool","emacs","software-quality","sublime","teamscale","vim"],"created_at":"2024-09-24T23:49:36.209Z","updated_at":"2025-10-31T17:30:32.256Z","avatar_url":"https://github.com/cqse.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Teamscale Pre-Commit Command-Line Client [![PyPI version](https://badge.fury.io/py/teamscale-cli.svg)](https://badge.fury.io/py/teamscale-cli) [![Teamscale Project](https://img.shields.io/badge/teamscale-teamscale--cli-brightgreen.svg)](https://demo.teamscale.com/activity.html#/teamscale-cli)\n\nThe [Teamscale](https://teamscale.com) pre-commit command-line interface (CLI) allows you to integrate pre-commit analysis in editors or IDEs such as VS Code, Emacs, QtCreator or Sublime by providing findings in a standard error format that is interpreted and displayed like compile errors by these editors.\n\n\u003e [!CAUTION]\n\u003e The Teamscale Pre-Commit CLI (`teamscale-cli`) is **deprecated** since February 2024.\n\u003e If using VS Code, please switch to our native [Teamscale Integration for Visual Studio Code](https://docs.teamscale.com/getting-started/visual-studio-code/).\n\u003e If integrating pre-commit in another IDE, please switch to the more feature-rich [Teamscale Command-Line Client for Developers (`teamscale-dev`)](https://docs.teamscale.com/getting-started/other-ides/) as soon as possible.\n\n## Installation\n\n**This guide uses `pip` and `python`. If you prefer Python 3, you'll probably have to replace all occurrences with `pip3` and `python3`.**\n\n1. Install [the latest release](https://pypi.org/project/teamscale-cli).\n2. Copy the example configuration file [.teamscale-precommit.config](./config/.teamscale-precommit.config) to the root directory of the repository you want to analyze. Edit it and insert all the necessary data. You can find your personal access token by opening Teamscale and clicking on your Avatar in the top right corner.\n3. Use `teamscale-cli` as a compile or build command in your editor. See below for instructions for\n    [sample configurations for some editors and IDEs below](#instructions-for-popular-editors).\n    Provide a file or folder within your repository as input. The general invocation looks like this:\n\n    ```bash\n    $ teamscale-cli [OPTIONS] CURRENTLY_OPENED_EDITOR_FILE\n    ```\n\nIf you already have a Python installation, you may alternatively install `teamscale-cli` via `pip install teamscale-cli`.\n\n## How it works\n\n`teamscale-cli` will use the path you specify on the command line to locate your .git directory. It then uploads all [local uncommitted changes known to Git](#how-does-change-detection-work) to the Teamscale server and project you configured in the config file. The client then waits until Teamscale has analyzed these changes, and outputs findings on `stdout` in the following format:\n\n```\nPath to file:line number:Column: (warning|error): Message\n```\n\nThis allows you to use the highlighting capabilities of your editors to highlight lines with findings in the editor and to jump to the finding location from the pre-commit console output. For your convenience, we've provided [sample configurations for some editors and IDEs below](#instructions-for-popular-editors).\n\nWhich findings are output is controlled by several command-line options:\n\n```\nteamscale-cli CURRENTLY_OPENED_EDITOR_FILE\n```\n\nwill output only pre-commit findings, i.e. findings that were added or removed due to your local changes. This includes all changes known to Git, not just the `CURRENTLY_OPENED_EDITOR_FILE`. Existing findings will not be output.\nUse this if you are only interested in the impact your local code changes will have on the findings.\n\n```\nteamscale-cli --fetch-existing-findings CURRENTLY_OPENED_EDITOR_FILE\n```\n\nwill output pre-commit findings for all locally changed files plus all existing, unchanged findings in `CURRENTLY_OPENED_EDITOR_FILE`.\nUse this if you also want to have a look at existing findings in the currently opened file, e.g. to clean up old findings while you code.\n**We recommend you use this mode as you can use it to see both the existing findings in the currently opened file (regardless of whether it is changed locally or not) and the impact of your local changes before you commit them. This gives you the opportunity to look at existing findings in the files you open and clean some of them up while you work on your code.**\n\n```\nteamscale-cli --fetch-existing-findings-in-changes CURRENTLY_OPENED_EDITOR_FILE\n```\n\nwill output pre-commit findings for all locally changed files plus all existing, unchanged findings in all locally changed files.\nUse this if you always want to clean up in all files where you have made changes.\n\nRun the client with the `-h` argument to see additional available options.\n\n## Instructions for Popular Editors\n\n### Sublime\n\nAdd a new *Build System* under `Tools \u003e Build System`. Copy and paste [our example snippet](./config/teamscale-precommit.sublime-build) and modify the arguments to fit your needs.\n\n### Xcode\n\nAdd a new *Build Phase* (`New Run Script Phase`) to your project. Enter the following command as shell script in that phase (see screenshot):\n\n```bash\npython -c 'from teamscale_precommit_client.precommit_client import run;run()' ${SRCROOT}\n```\n\nThis script uses `python` to execute the Teamscale precommit command-line interface on the source of the project's Git repository (`SCROOT`). Make sure to use the correct Python version in that snippet, which might be `python3`. \nAlso, keep in mind that `python` by default might point to Xcode's own copy of python. Hence, you might want to explicitly specify the python executable's path instead (e.g. `/usr/bin/python`).\n\n**In Xcode you cannot use `--fetch-existing-findings` since there is unfortunately no environment variable for the currently opened editor file.\nUsing this flag would give you all findings in the entire project, which is usually not helpful.**\n\n![Configuring the Build Phase in Xcode](config/xcode_1.png)\n\nScreenshot of findings shown in Xcode:\n\n![Teamscale Findings in Xcode](config/xcode_2.png)\n\nAs shown on the previous screenshot, Xcode also provides links to the corresponding finding in Teamscale.\n\n### VS Code\n\nAdd a new task (`Terminal \u003e Configure Tasks \u003e Create tasks.json file from template \u003e Others`) and name it `Teamscale Pre-Commit Analysis`. VS Code will open a sample `tasks.json` for you to edit. Copy and paste [the example snippet from this repo](./config/teamscale-precommit-vscode-task.json).\n\n### Vim\n\nCopy [the teamscale-cli vim file](./config/teamscale.vim) to `~/.vim/compiler` and restart Vim.\nThis should allow you to run `:compiler teamscale` and `:make %`. Then, you should be able to use your usual workflow (e.g. `:cn`) to go through the findings.\n\n### Qt Creator\n\nIn order to use the pre-commit Analysis in Qt Creator you need to add a new Kit (Teamscale does _not_ have to be the default Kit).\nGo to `Tools \u003e Options \u003e Kits \u003e Add`  \n\n![New Teamscale Kit](config/qtcreator_1.png)\n\nThe compiler must be set to gcc as this will be used to parse the console output of the tool.\n\nNext you need to add the actual build config to each of your QtCreator projects.\nGo to `Projects \u003e Teamscale \u003e Build` and remove all default `Build` and `Clean Steps` (there should be a small `x` when hovering over them).\nAdd a new build configuration:\n\n![Pre-Commit](config/qtcreator_2.png)\n\nThen configure it as follows:  \n\n* Executable: `python`\n* Command-line arguments: `-c \"from teamscale_precommit_client.precommit_client import run;run()\" --fetch-existing-findings --log-to-stderr %{CurrentDocument:FilePath}`\n\nThe flag `--log-to-stderr` is required as otherwise QtCreator will not recognize the findings.  \n\nYou can add more than one build configuration, e.g. if you sometimes want to run the teamscale-cli with different arguments.\n\n## How does change detection work?\n\nThe client detects changes by querying your Git repository for its current status. The following change types will be considered:\n\n- Modified files\n- Renamed files\n- Files added to the index\n- Deleted files that were in the index\n\nNew files that are not in the index will be ignored.\n\n## Troubleshooting\n\n- If python does not find the name `ConverterMapping` try uninstalling the `python-configparser` system package and install `configparser` via pip.\n- If your files are not uploaded for pre-commit analysis make sure that you specified the correct encoding with the `--file-encoding` option. By default, the system encoding will be used for decoding.\n\n## Limits\n\nThe precommit analysis has some builtin limits whose goal is to prevent denial of service of the Teamscale server:\n\n- Files uploaded for precommit analysis must be less than 1 MB in size.\n- At most 20 files can be uploaded for precommit analysis (can be changed on the server).\n- Precommit analysis uploads might only be done once every 5 seconds per user (can be changed on the server).\n\nThese are automatically applied and cannot be disabled.\n\n# Developing\n\n## Preparation\n\n1. Install [pip](https://pypi.org/project/pip/), e.g. via your system's package manager.\n2. Install all dependencies:\n   ```sh\n   pip install .\n   ```\n\n## Building\n\n```sh\npython setup.py build\n```\n\n## Running Tests\n\n```sh\npython setup.py test\n```\n\n## Releasing\n\n1. Create a GitHub release with the current Teamscale version number.\n2. A GitHub action will automatically be triggered that builds the released branch and attaches the binaries to the release.\n3. Contact Thomas Kinnen to perform the release to PyPI.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcqse%2Fteamscale-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcqse%2Fteamscale-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcqse%2Fteamscale-cli/lists"}