Go to file
Dandaedre 942e58970e
VSG fork CI VSG tests and package installation checks passed.
MadGobblins/vhdl-style-guide/pipeline/head This commit looks good Details
Add fork maintenance and package publishing
2026-10-02 20:30:56 +02:00
.github Issue#1442: Ensuring ISO-8859 encoded files are written as ISO-8859 encoded files (#1463) 2025-07-04 14:10:49 -05:00
bin style: apply black 2024-03-24 21:16:35 +02:00
docs Merge pull request #1559 from JHertz5/issue-1555 2026-05-29 08:10:46 +01:00
tests Add fixed VHDL output on stdout 2026-10-02 19:47:54 +02:00
vsg Add fixed VHDL output on stdout 2026-10-02 19:47:54 +02:00
.codespell-ignore style: apply codespell 2024-03-24 21:16:34 +02:00
.flake8 build: PEP 517 build with tox 2024-03-24 21:16:34 +02:00
.gitattributes cleanup: dos2unix 2024-03-23 12:11:19 +02:00
.gitignore Add fork maintenance and package publishing 2026-10-02 20:30:56 +02:00
.pre-commit-config.yaml Issue#1442: Ensuring ISO-8859 encoded files are written as ISO-8859 encoded files (#1463) 2025-07-04 14:10:49 -05:00
.pre-commit-hooks.yaml alonbl patch series (#1017) 2023-11-05 07:24:50 -06:00
.readthedocs.yaml build: PEP 517 build with tox 2024-03-24 21:16:34 +02:00
CODE_OF_CONDUCT.md Create CODE_OF_CONDUCT.md 2018-11-01 23:25:42 -05:00
Jenkinsfile Add fork maintenance and package publishing 2026-10-02 20:30:56 +02:00
LICENSE Initial commit 2017-07-03 13:24:44 -05:00
MANIFEST.in Fixing tox style errors. 2024-10-20 18:35:25 -05:00
README.rst Add fork maintenance and package publishing 2026-10-02 20:30:56 +02:00
build-package.sh Add fork maintenance and package publishing 2026-10-02 20:30:56 +02:00
pyproject.toml Issue#1442: Ensuring ISO-8859 encoded files are written as ISO-8859 encoded files (#1463) 2025-07-04 14:10:49 -05:00
sonar-project.properties Adding sonarcloud analysis. 2021-03-20 15:08:20 -05:00
tox.ini Issue#1442: Ensuring ISO-8859 encoded files are written as ISO-8859 encoded files (#1463) 2025-07-04 14:10:49 -05:00
update-fork.sh Add fork maintenance and package publishing 2026-10-02 20:30:56 +02:00

README.rst

VHDL Style Guide (VSG)
======================

**Coding style enforcement for VHDL.**

.. image:: https://img.shields.io/github/tag/jeremiah-c-leary/vhdl-style-guide.svg?style=flat-square
   :target: https://github.com/jeremiah-c-leary/vhdl-style-guide
   :alt: Github Release
.. image:: https://img.shields.io/pypi/v/vsg.svg?style=flat-square
   :target: https://pypi.python.org/pypi/vsg
   :alt: PyPI Version
.. image:: https://img.shields.io/codecov/c/github/jeremiah-c-leary/vhdl-style-guide/master.svg?style=flat-square
   :target: https://codecov.io/github/jeremiah-c-leary/vhdl-style-guide
   :alt: Test Coverage
.. image:: https://img.shields.io/readthedocs/vsg.svg?style=flat-square
   :target: http://vhdl-style-guide.readthedocs.io/en/latest/index.html
   :alt: Read The Docs
.. image:: https://api.codacy.com/project/badge/Grade/42744dca97544824b93cfc99e8030063
   :target: https://www.codacy.com/app/jeremiah-c-leary/vhdl-style-guide?utm_source=github.com&utm_medium=referral&utm_content=jeremiah-c-leary/vhdl-style-guide&utm_campaign=Badge_Grade
   :alt: Codacy

Announcements
-------------

Update 11/09/2025

Where has Jeremy been?

Just wanted to let everyone know that I have not abandoned this project.
There was a family emergency I had to handle and now work is taking a significant amount of my time.

I plan to start working on this again in December.

Regards,

--Jeremy

.. image:: https://github.com/jeremiah-c-leary/vhdl-style-guide/blob/master/docs/img/vim_macro.gif

Table of Contents
-----------------

*   `Overview`_
*   `Key Benefits`_
*   `Key Features`_
*   `Known Limitations`_
*   `Installation`_
*   `Usage`_
*   `Documentation`_
*   `Contributing`_

Overview
--------

VSG was created after participating in a code review where a real issue in the code was masked by a coding style issue.
A finding was created for the style issue, while the real issue was missed.
When the code was re-reviewed, the real issue was discovered.

Depending on your process, style issues can take a lot of time to resolve.

#. Create finding/ticket/issue
#. Disposition finding/ticket/issue
#. Fix
#. Verify fix

Spending less time on style issues leaves more time to analyze the substance of the code.
This ultimately reduces the amount of time performing code reviews.
It also allows reviewers to focus on the substance of the code.
This will result in a higher quality code base.

Key Benefits
------------

* Define VHDL coding standards
* Makes coding standards visible to everyone
* Improve code reviews
* Quickly bring code up to current standards

VSG allows the style of the code to be defined and enforced over part or the entire code base.
Configurations allow for multiple coding standards.

Key Features
------------

* Command line tool

  * integrate into continuous integration flow with JUnit output

* Reports and fixes issues found

  * whitespace

    * horizontal
    * vertical

  * upper and lower case
  * keyword alignments
  * etc...

* Fully configurable rules via JSON or YAML configuration file

  * Disable rules
  * Alter behavior of existing rules

* Localize rule sets

  * Create your own rules using python
  * Use existing rules as a template
  * Fully integrates into base rule set

* Built in styles

  * Use existing style or create your own

Known Limitations
-----------------

VSG is a continual work in progress.
As such, this version has the following known limitations:

* Parser will not process embedded PSL
* Parser will not process VHDL 2019

Installation
------------

You can get the latest released version of VSG via **pip**.

.. code-block:: bash

    pip install vsg

The latest development version can be cloned...

.. code-block:: bash

    git clone https://github.com/jeremiah-c-leary/vhdl-style-guide.git

Install prerequisites.

.. code-block:: bash

    pip install tox

Build locally, artifacts will appear in ``dist`` directory.

.. code-block:: bash

    tox

Fork for ``vsg_bridge_ls``
~~~~~~~~~~~~~~~~~~~~~~~~~

This fork adds ``--stdout`` and ``--no-failure`` so VSG can format editor
buffers through standard streams. It is the VSG backend required for formatting
with `vsg_bridge_ls <https://proxy.dandaedre.com/gitea/MadGobblins/vsg_bridge_ls>`_.
The bridge README is the main user guide for installing both projects and
configuring an editor.

The preferred installation uses uv and the prebuilt Gitea package:

.. code-block:: bash

    uv venv .venv
    uv pip install --python .venv/bin/python \
      --index https://proxy.dandaedre.com/gitea/api/packages/MadGobblins/pypi/simple/ \
      vsg

Installing from ``master`` also works with uv, and either source works with
standard pip. See the bridge's
`installation guide <https://proxy.dandaedre.com/gitea/MadGobblins/vsg_bridge_ls/src/branch/main/doc/installation.md>`_
for all supported commands and environment setup.

Fork maintainers can build locally with ``./build-package.sh`` and publish the
new artifacts with:

.. code-block:: bash

    ./build-package.sh ../gitea_token.txt --publish

On ``master``, Jenkins fetches the Git tags used by
``setuptools-git-versioning``, runs both installation smoke tests, archives the
generated distributions, and publishes those exact artifacts to Gitea. The
required Jenkins credential is documented in the bridge development guide.

Use ``./update-fork.sh`` to fetch upstream tags and rebase the small fork patch
series onto the latest upstream ``master``. The script requires a clean
worktree and automatically aborts a failed rebase.

Usage
-----

VSG is a both a command line tool and a python package.
The command line tool can be invoked with:

.. code-block:: bash

   $ vsg
   usage: VHDL Style Guide (VSG) [-h] [-f FILENAME [FILENAME ...]] [-lr LOCAL_RULES] [-c CONFIGURATION [CONFIGURATION ...]] [--fix]
                                 [-fp FIX_PHASE] [-j JUNIT] [-js JSON] [-of {vsg,syntastic,summary}] [-b] [-oc OUTPUT_CONFIGURATION]
                                 [-rc RULE_CONFIGURATION] [--style {indent_only,jcl}] [-v] [-ap] [--fix_only FIX_ONLY] [--stdin]
                                 [--quality_report QUALITY_REPORT] [-p JOBS] [--debug]
                                 [FILENAME ...]

   Analyzes VHDL files for style guide violations. Reference documentation is located at: http://vhdl-style-guide.readthedocs.io/en/latest/index.html

   positional arguments:
     FILENAME              File to analyze

   options:
     -h, --help            show this help message and exit
     -f FILENAME [FILENAME ...], --filename FILENAME [FILENAME ...]
                           File to analyze
     -lr LOCAL_RULES, --local_rules LOCAL_RULES
                           Path to local rules
     -c CONFIGURATION [CONFIGURATION ...], --configuration CONFIGURATION [CONFIGURATION ...]
                           JSON or YAML configuration file(s)
     --fix                 Fix issues found
     -fp FIX_PHASE, --fix_phase FIX_PHASE
                           Fix issues up to and including this phase
     -j JUNIT, --junit JUNIT
                           Extract Junit file
     -js JSON, --json JSON
                           Extract JSON file
     -of {vsg,syntastic,summary}, --output_format {vsg,syntastic,summary}
                           Sets the output format.
     -b, --backup          Creates a copy of input file for comparison with fixed version.
     -oc OUTPUT_CONFIGURATION, --output_configuration OUTPUT_CONFIGURATION
                           Write configuration to file name.
     -rc RULE_CONFIGURATION, --rule_configuration RULE_CONFIGURATION
                           Display configuration of a rule
     --style {indent_only,jcl}
                           Use predefined style
     -v, --version         Displays version information
     -ap, --all_phases     Do not stop when a violation is detected.
     --fix_only FIX_ONLY   Restrict fixing via JSON file.
     --stdin               Read VHDL input from stdin, disables all other file selections, disables multiprocessing
     --quality_report QUALITY_REPORT
                           Create code quality report for GitLab
     -p JOBS, --jobs JOBS  number of parallel jobs to use, default is the number of cpu cores
     --debug               Displays verbose debug information

Here is an example output running against a test file:

.. image:: https://github.com/jeremiah-c-leary/vhdl-style-guide/blob/master/docs/img/fixing_single_file.gif

pre-commit Integration
----------------------

Here is an example of ``.pre-commit-config.yaml`` file:

.. code-block:: yaml

  repos:
    - repo: https://github.com/jeremiah-c-leary/vhdl-style-guide
      rev: v3.18.0
      hooks:
        - id: vsg

Documentation
-------------

All documentation for VSG is hosted at `read-the-docs <http://vhdl-style-guide.readthedocs.io/en/latest/index.html>`_.

Contributing
------------

I welcome any contributions to this project.
No matter how small or large.

There are several ways to contribute:

* Bug reports
* Code base improvements
* Feature requests
* Pull requests

Please refer to the documentation hosted at `read-the-docs <http://vhdl-style-guide.readthedocs.io/en/latest/index.html>`_ for more details on contributing.