Importing games

The Import games window opens from the button in the toolbar or from File › Import games… (⇧⌘I), and opens on the tab of the last import. From an opponent’s dossier, Download their games… opens it on their site, with their name already written and Everything set.

At the top are the four tabs: PGN file, Paste, chess.com and lichess.org. Below, the panel of the one chosen; at the bottom Import into, Cancel and the button that imports. What is imported is the tab you see: the others keep what is in them, for later.

PGN file

A .pgn file is dragged into the dashed area (“Drop a PGN file here”), or chosen with Choose a file…; dragged anywhere on the window, from any tab, it leads to PGN file. Once the file is chosen, it shows its card: the name, how many games it holds, the size, Discard and Choose another file…. The button becomes Import N games. Size is not a problem: the file is read a piece at a time, even with millions of games.

A .pgn file opened with a double click in the Finder, dragged onto the app’s icon in the Dock or opened with Open With › Terza Torre opens this window with the file ready: it does not import by itself.

A file exported from an online study offers Choose where each chapter goes…, like the studies below.

Paste

Paste from the clipboard puts the PGN text you copied into the box; a second paste adds it after. You can also type or paste straight into the box. Below, how many games it found, and Clear.

chess.com and lichess.org

You write the Account name and choose How far back: Last year, Last 3 years, Last 5 years or Everything. Under the field are Your accounts:, that site’s accounts written in your profile, and with Pro Your opponents:, those of the opponent dossiers: a click writes the name. But anyone’s name will do, a friend’s, a coach’s, an opponent’s: no passwords are needed, and the site receives only the name.

If the profile has no account on that site, Is this your account? appears under a new name, with Add to my profile.

Download and import checks the account first: a name that does not exist, or a period without games, is reported under the field, and the window stays open. Otherwise the window closes, and the download and import carry on in the background, under Background work at the bottom of the sidebar: first “Downloading from …” with the games received, then the import. Stop works for both. If you quit the app while it is downloading, the app warns you that the download will be lost and that nothing is in the archive yet.

chess.com gives the games month by month, and the period goes by whole months: Last year, in mid-October, starts from October of the year before. If some month does not arrive, the report says how many: downloading again, the games you already have are not added twice. chess.com has no studies, and its game collections are downloaded one at a time as PGN from the site, to be imported afterwards as files.
lichess sends the games one after another, and the window says how fast: about 20 a second without signing in, so a long history takes a few minutes; signed in to lichess, about 30 a second for other people’s games and about 60 for yours.

Signing in to lichess is optional, and is offered only for an account of yours: Sign in to lichess…, under the name, opens the lichess page where you give permission. Once signed in, your games download three times faster and you also see your private studies; Sign out removes the connection. The same is done from Settings › Profile: see Profile.

lichess studies

In the lichess.org tab, at the top, you choose between Games and Studies. With Studies the field takes a player’s name or the link of a study.

Find studies finds that player’s public studies; for an account of yours, signed in, the private ones too. You tick the ones to import (Tick all, Untick all) and go Next.
The app reads the chapters and shows them one by one, each with where it goes: Study, Game, Leave out and, with Pro, for your studies that start from the initial position, White repertoire and study or Black repertoire and study. A chapter with players or a result is suggested as a game; an opening line from a study of yours, with Pro, goes into the repertoire of the colour you look at it from; the rest as a study. A chapter for the repertoire is also saved as a study: the repertoire keeps only the moves, the study the comments and variations too. A chapter that cannot be read, or an empty one, stays out.
Import puts them where you chose. A chapter you already have, with the same content, is not added twice.

A private study you take part in, your coach’s for example, does not appear in the list, because it is private to its owner’s account: paste its link, signed in to lichess, and you will be able to import it, unless the owner has kept exporting to themselves. In that case lichess does not let it be downloaded, and the window says so: you have to ask them.

Imported studies are in Studies, in the sidebar: see Studies.

Import into

The menu at the bottom also puts the imported games into a collection, or into a new one with New collection…. The collection also gets the duplicate games the archive already had: so it holds everything you imported, without second copies in the archive.

While importing

The button closes the window and the import carries on in the background: under Background work, at the bottom of the sidebar, are the progress and Stop. The list updates at the end. Games are written in blocks of a few thousand: if you stop, or close the app, those already written stay. If you quit during an import, the app asks first.

One import at a time: with one already running, the window says so above the button, with its bar. While it works, the Mac does not go to sleep by itself.

The report

At the end it stays on the screen until you close it with OK: Import complete, Import stopped, or Import interrupted by an error with the error. The lines, only those with a number:

how many games were imported;
how many were already in your archive;
for how many the annotations were added to the copy you had, and how many were not imported because they differ from the ones you have (see duplicates, below);
how many could not be read, and how many are not standard chess;
from chess.com, the months not downloaded;
from lichess studies, the chapters saved as studies, those you already had, the moves added to each repertoire and the chapters left out.

If you have a repertoire and the new games include yours, the report also says whether any of them left it, and Show in the repertoire takes you to see where.

The games added are in Last import, in the sidebar: only the new ones, not the duplicates.

Duplicates

Two games are the same when these are equal:

the two players. A player with a FIDE ID is that ID, and the name does not count: two different IDs are two players even with the same name, and a copy with the ID and one without are two players. Without an ID what counts are the words of the name, in any order, regardless of capitals, accents and punctuation: “Carlsen,Magnus”, “Carlsen, Magnus”, “CARLSEN Magnus” and “Magnus Carlsen” are the same name, “Carlsen, M.” is not, and neither is the nickname “magnus-carlsen”, which is another player (see Player names);
the date, including the parts that are missing: “1999” and “20 January 1999” are different dates;
the result;
the starting position and the moves of the main line.

Tournament, site, Elo and annotations do not count.

The duplicate does not go in, and the data of its header is not merged with yours. Its annotations — comments, symbols, variations, times, evaluations — go onto your copy only if yours has none; if both have them and they differ, yours stays as it is and the report counts them.

For duplicates already in the archive there is Remove duplicates: see Archive health.

What changes on the way in

Chess variants. A game of Chess960 or another variant does not go in. Games from a set-up position do.
Online or over the board. It is decided game by game: a game is online when it was played on the Internet according to its site (for example “INT”), or exported from an online site. The tournament’s name does not count. If it gets it wrong, right click → Mark as online or Mark as over the board, and export keeps your choice.
The opening (ECO code, name and variation) is always recognised by the app, from the moves: the one written in the file is not used.
People’s names take the usual form: “ROSSI,Mario” becomes “Rossi, Mario”. Not nicknames, nor names with digits or “_”, nor games downloaded from the sites.
Tags the app does not have, and values outside its lists, are lost. Placeholders like “?” become empty fields.

Files

PGN only. The text can be in UTF-8 or, line by line, in the encoding of old Windows programs: mixed files are fine. Whatever lies between one game and the next, like the headings in TWIC files, is ignored.

Without the window

A PGN file dragged from the Finder onto the main window is imported at once: into the collection you are looking at, into Favourites with the star, otherwise only into the archive. Dropped on a row of the sidebar, Favourites or a collection, it goes into that list. While the file is over the window, a veil says where it will go. There is no limit on games, and under Background work there is Stop. Several files at once, a file that is not .pgn, one without games or unreadable, or an import already running: nothing is imported, and a notice says why.
⌘V on the list of games imports the PGN on the clipboard, up to 100 games (see The main window). For more, a file.