<!--
metadata:
  title: "GitHub Linguist and statistics"
  platform: "github"
  objective: "How to correct the repository language statistics bar using .gitattributes."
  status: "draft"
  last_updated: "2026-04-29"
  tags: ["github", "linguist", "gitattributes", "stats"]
  agent_priority: "medium"
-->

# GitHub Linguist and statistics

> This file explains how to control GitHub's internal language detection engine (Linguist) to ensure your repository accurately reflects your core technical skills, rather than being skewed by vendor files.

---

## 1. Overview

GitHub displays a color-coded language statistics bar at the top of every repository (e.g., indicating a project is 60% Python, 40% JavaScript). This bar is generated by an open-source Ruby library called **Linguist**. 

Recruiters frequently glance at this bar to verify your primary skill set. However, Linguist calculates percentages based on total file byte size. If you commit a massive minified CSS framework or a large JSON dataset into a Go backend project, Linguist may incorrectly label your repository as "100% CSS" or "100% JSON," completely hiding your Go engineering work.

## 2. Using .gitattributes to override Linguist

You can explicitly instruct Linguist to ignore specific files or directories by using a `.gitattributes` file in the root of your repository.

**Rule:** Mark vendor, generated, and data files with the most accurate Linguist attribute. Use `linguist-vendored=true` for third-party dependencies, `linguist-generated=true` for generated output, and `linguist-documentation=true` for documentation-heavy folders. These attributes can remove files from language statistics and may affect code-search visibility, so use the narrowest truthful classification.

```text
# Example .gitattributes file

# Ignore large datasets
data/*.json linguist-generated=true
data/*.csv linguist-generated=true

# Ignore compiled/minified frontend assets
public/build/* linguist-vendored=true

# Ignore third-party libraries committed to the repo
vendor/* linguist-vendored=true

# Mark documentation folders (excludes from stats, keeps in search)
docs/* linguist-documentation=true

# Force a specific language to be detectable (useful for non-standard extensions)
*.myextension linguist-detectable=true
```

**Rule:** Force a specific language for ambiguous files. If Linguist misidentifies a file extension, you can force it to recognize the correct language.

```text
# Treat all .h files as C++ instead of C
*.h linguist-language=C++
```

## 3. Impact on Search Indexing

**Rule:** Understand that some Linguist overrides can affect code search visibility. GitHub code search excludes generated and vendored files from many search paths. This is generally the desired outcome for third-party bundles or generated artifacts, but do not mark first-party source code as vendored or generated just to change the language bar.

## 4. Anti-Patterns

### The 99% HTML backend

**What it looks like:** A complex Rust microservice repository where the language bar shows 95% HTML and 5% Rust because a large static documentation site is included in the `/docs` folder. **Why it fails:** A non-technical recruiter scanning your profile for Rust experience will see the HTML bar and assume this is a frontend web design project, potentially passing over your profile. **What to do instead:** Mark documentation as documentation with `docs/* linguist-documentation=true`, or mark generated documentation output as generated when that is accurate. Use Linguist overrides to describe the repository honestly, not to hide first-party source code.

---

*Next step: Leverage social proof in [Engagement signals](./engagement-signals.md).*
