mirror of https://github.com/theNewDynamic/gohugo-theme-ananke.git
edit | blame | history | raw

synch-social-icons.ts

Synchronises local SVG icons with the upstream simple-icons repository.

The script is intended for folders such as assets/ananke/socials/ that already contain SVG icon files. By default it runs in dry-run mode, compares local files with upstream files from simple-icons/icons/, and reports what would change.

Usage

Run in dry-run mode against existing local files only:

node src/scripts/update-social-icons.ts

Run in dry-run mode and show only non-identical results:

node src/scripts/update-social-icons.ts --only-changed

Apply updates to changed local files:

node src/scripts/update-social-icons.ts --apply

Apply updates and delete local files that are not present upstream:

node src/scripts/update-social-icons.ts --apply --delete

Sync against all upstream icons instead of only the files already present locally:

node src/scripts/update-social-icons.ts --all

Create missing local files from upstream:

node src/scripts/update-social-icons.ts --all --apply

Full sync mode including deletion of extra local files:

node src/scripts/update-social-icons.ts --all --apply --delete

Return JSON output for scripting or automation:

node src/scripts/update-social-icons.ts --all --only-changed --json

Set a custom target folder:

node src/scripts/update-social-icons.ts --dir=assets/ananke/socials

Use a different upstream branch:

node src/scripts/update-social-icons.ts --branch=develop

Reduce or increase concurrency:

node src/scripts/update-social-icons.ts --all --concurrency=4

CLI options

  • --dir <path>

  • Directory containing local SVG icons

  • Default: assets/ananke/socials

  • --branch <name>

  • Branch in the simple-icons repository

  • Default: develop

  • --apply

  • Actually write changes to disk

  • Without this flag the script only reports what would happen

  • --delete

  • Delete local SVG files that do not exist upstream

  • In dry-run mode this reports would-delete
  • In apply mode this deletes files

  • --all

  • Use the complete upstream icon directory as the source of truth

  • Missing local files become would-create in dry-run mode
  • Missing local files are created in apply mode
  • Extra local files can be removed when combined with --delete

  • --only-changed

  • Hide same results

  • Useful for shorter reports

  • --json

  • Print machine-readable JSON output instead of text output

  • --verbose

  • Show local path and remote URL for each printed result

  • --concurrency <n>

  • Number of parallel file checks/downloads

  • Default: 8

  • --help

  • Show usage help

Behaviour

Default mode

Without --all, the script only checks local .svg files that already exist in the target directory.

For each local file:

  • it tries to fetch the matching file from simple-icons/icons/<filename>
  • if the upstream file is identical, the result is same
  • if the upstream file differs, the result is changed
  • if the upstream file does not exist, the result is:

  • missing without --delete

  • would-delete with --delete in dry-run mode
  • deleted with --delete --apply

Full sync mode

With --all, the script first loads the full upstream icon listing from simple-icons/icons/.

For each upstream file:

  • if the local file does not exist:

  • would-create in dry-run mode

  • created in apply mode
  • if the local file exists and is identical:

  • same

  • if the local file exists and differs:

  • changed in dry-run mode

  • updated in apply mode

For local files that do not exist upstream:

  • missing without --delete
  • would-delete with --delete in dry-run mode
  • deleted with --delete --apply

Output states

  • same

  • local file matches upstream

  • changed

  • local file exists, upstream exists, content differs

  • missing

  • local file exists, upstream file does not exist, and deletion is not enabled

  • would-create

  • upstream file exists, local file does not exist, dry-run mode

  • created

  • upstream file exists, local file did not exist, file was created

  • would-delete

  • local file exists, upstream file does not exist, dry-run mode with --delete

  • deleted

  • local file existed, upstream file does not exist, file was deleted

  • updated

  • local file existed, upstream file exists, file was overwritten

  • error

  • processing failed for that file

Progress output

During text-mode execution, the script shows a one-line progress indicator:

Processing 42/180 (active: 5)

This line updates while work is in progress. Individual file results are printed as they complete.

Because processing is concurrent, results may appear in completion order rather than alphabetical order.

JSON output

When --json is used, the script prints a single JSON object containing:

  • options
  • results
  • summary

This is useful for automation or piping into other tools.

Example:

{
  "options": {
    "dir": "/path/to/assets/ananke/socials",
    "branch": "develop",
    "apply": false,
    "deleteMissing": false,
    "onlyChanged": true,
    "json": true,
    "verbose": false,
    "all": true,
    "concurrency": 8
  },
  "results": [
    {
      "fileName": "github.svg",
      "localPath": "/path/to/assets/ananke/socials/github.svg",
      "remoteUrl": "https://raw.githubusercontent.com/simple-icons/simple-icons/develop/icons/github.svg",
      "status": "changed",
      "message": "Upstream file differs from local file"
    }
  ],
  "summary": {
    "same": 0,
    "changed": 1,
    "missing": 0,
    "wouldCreate": 0,
    "created": 0,
    "wouldDelete": 0,
    "deleted": 0,
    "updated": 0,
    "errors": 0
  }
}

Recommendations

  • Use dry-run first:

  • node src/scripts/update-social-icons.ts --only-changed

  • For full folder sync:

  • node src/scripts/update-social-icons.ts --all --only-changed

  • For actual updates:

  • node src/scripts/update-social-icons.ts --all --apply

  • For strict mirroring of upstream:

  • node src/scripts/update-social-icons.ts --all --apply --delete

Notes

  • Matching is filename-based only.
  • The script only works with .svg files.
  • In --all mode, extra custom local icons may be deleted if --delete is also used.
  • The script uses the GitHub contents API once to list files in simple-icons/icons/, then raw file URLs for SVG downloads.
  • A moderate concurrency like 4 to 8 is usually a good default.

Adding new icons

  • add the new icon to assets/ananke/socials/ with the correct filename (e.g. myicon.svg)
  • it doesn't matter if the content matches the upstream version, as the script will update it
  • run the script in dry-run mode to verify the new icon is detected as changed
  • run the script with --apply to update the new icon from upstream