# What Is flag_order.txt and How Does It Sort Country Flags in Free-TV/IPTV?

> Discover how flag_order.txt sorts country flags in Free-TV/IPTV. Learn its role in defining display order for optimized country flag presentation.

- Repository: [Free TV/IPTV](https://github.com/Free-TV/IPTV)
- Tags: internals
- Published: 2026-06-17

---

**[`flag_order.txt`](https://github.com/Free-TV/IPTV/blob/main/flag_order.txt) is the authoritative sorting guide that defines the display order of country flags on the main page of the Free-TV/IPTV repository by providing an ordered list of country identifiers processed by [`make_flags.sh`](https://github.com/Free-TV/IPTV/blob/main/make_flags.sh).**

The Free-TV/IPTV project organizes television channel lists by country, displaying a horizontal flag bar in the [`README.md`](https://github.com/Free-TV/IPTV/blob/main/README.md) for quick navigation. The [`flag_order.txt`](https://github.com/Free-TV/IPTV/blob/main/flag_order.txt) file acts as the single source of truth for the visual sequence of these flags, allowing maintainers to customize the geographic layout without manually editing the final documentation.

## How flag_order.txt Controls Flag Display Order

The [`flag_order.txt`](https://github.com/Free-TV/IPTV/blob/main/flag_order.txt) file in the repository root serves as a **declarative configuration** that groups countries into logical sections such as *Anglosphere*, *Asia*, *Europe*, *Middle East*, *Americas*, and *Africa*.

Each line in the file contains a country identifier (e.g., `usa`, `uk`, `japan`) that corresponds to a specific markdown list file in the `lists/` directory. The script [`make_flags.sh`](https://github.com/Free-TV/IPTV/blob/main/make_flags.sh) processes these identifiers sequentially, meaning the visual order of flags in the README directly mirrors the line order in [`flag_order.txt`](https://github.com/Free-TV/IPTV/blob/main/flag_order.txt).

The file supports organizational formatting:
- **Blank lines** are ignored during processing
- **Comment lines** starting with `#` are filtered out
- **Underscores** in identifiers represent spaces (e.g., `czech_republic`)

## The make_flags.sh Processing Pipeline

According to the Free-TV/IPTV source code, the shell script [`make_flags.sh`](https://github.com/Free-TV/IPTV/blob/main/make_flags.sh) implements the logic that transforms the raw text file into clickable flag icons.

### Reading and Filtering the List

The script iterates over [`flag_order.txt`](https://github.com/Free-TV/IPTV/blob/main/flag_order.txt) using a loop that explicitly removes blank lines and comments:

```bash
for country in `cat ./flag_order.txt | grep -v "^$" | grep -v "#"`; do
    # Processing logic here

done

```

This ensures that only valid country identifiers enter the processing pipeline.

### Transforming Identifiers to Country Codes

For each identifier, the script performs several normalizations:
- Converts underscores to spaces using `sed -e "s/_/ /g"`
- Handles special cases for `korea` (mapped to "south korea") and `uk` (mapped to "united kingdom")
- Looks up the two-letter ISO code from `countries.list`

The script then generates Markdown image links pointing to the Circle Flags CDN:

```bash
echo "[<img src=\"https://hatscripts.github.io/circle-flags/flags/$country_code.svg\" width=\"24\">](lists/$country.md)"

```

For example, the identifier `usa` produces:

```markdown
[<img src="https://hatscripts.github.io/circle-flags/flags/us.svg" width="24">](lists/usa.md)

```

## Customizing Country Display Order

To rearrange, add, or remove countries from the flag bar, edit [`flag_order.txt`](https://github.com/Free-TV/IPTV/blob/main/flag_order.txt) directly. After modifying the file, run [`make_flags.sh`](https://github.com/Free-TV/IPTV/blob/main/make_flags.sh) to regenerate the flag bar section of the README.

The script validates every entry against `countries.list` and exits with an error if an identifier lacks a corresponding ISO code:

```bash
if [[ -z "$country_code_line" ]]; then
    echo "MISSING COUNTRY CODE FOR: $country"
    exit 1
fi

```

This validation ensures that the generated README only contains valid, resolvable country links.

## Summary

- **[`flag_order.txt`](https://github.com/Free-TV/IPTV/blob/main/flag_order.txt)** defines the authoritative display order for country flags in the Free-TV/IPTV repository.
- The file uses simple line-based ordering where each line represents a country identifier, with blank lines and `#` comments ignored.
- **[`make_flags.sh`](https://github.com/Free-TV/IPTV/blob/main/make_flags.sh)** reads this file sequentially, looks up ISO codes in `countries.list`, and generates Markdown flag links.
- Editing [`flag_order.txt`](https://github.com/Free-TV/IPTV/blob/main/flag_order.txt) and re-running the script automatically updates the visual flag bar in [`README.md`](https://github.com/Free-TV/IPTV/blob/main/README.md) without manual HTML manipulation.

## Frequently Asked Questions

### What format does flag_order.txt use?

The file uses plain text with one country identifier per line. Identifiers use underscores instead of spaces (e.g., `united_kingdom`), and lines beginning with `#` are treated as comments. The order of lines determines the final left-to-right display of flags in the README.

### How does make_flags.sh handle comments and blank lines?

The script filters out both empty lines and comments using chained `grep` commands: `grep -v "^$"` removes blank lines, and `grep -v "#"` removes comment lines. This ensures the loop only processes valid country identifiers.

### Can I add new countries to the flag bar?

Yes. Add the country identifier to [`flag_order.txt`](https://github.com/Free-TV/IPTV/blob/main/flag_order.txt) in your desired position, ensure the corresponding `countries.list` entry exists with the proper ISO code, and run [`make_flags.sh`](https://github.com/Free-TV/IPTV/blob/main/make_flags.sh). The script validates the entry and generates the appropriate flag link if the country code is found.

### Where does the flag imagery come from?

The script generates URLs pointing to the Circle Flags CDN (`https://hatscripts.github.io/circle-flags/flags/`), appending the lowercase two-letter ISO country code and `.svg` extension. The width is fixed at 24 pixels to maintain consistent alignment in the flag bar.