Skip to content

contacts-dedupe.md

Latest commit

 

History

History
131 lines (97 loc) · 3.39 KB

contacts-dedupe.md

File metadata and controls

131 lines (97 loc) · 3.39 KB
Raw

Contacts Dedupe

read_when:

  • Finding duplicate Google Contacts.
  • Reviewing or changing gog contacts dedupe.

gog contacts dedupe finds likely duplicate personal contacts and prints a merge plan. Preview is the default; --apply performs the reviewed plan.

Command Page

Basic Use

gog contacts dedupe
gog contacts dedupe --json
gog contacts dedupe --max 500 --json

Default matching uses normalized email and phone values:

gog contacts dedupe --match email,phone

Name matching is opt-in because it can produce false positives:

gog contacts dedupe --match email,phone,name

Apply A Merge

Review the plan first:

gog contacts dedupe --json

Then inspect the exact mutation plan without changing contacts:

gog contacts dedupe --apply --dry-run --json

For automation, copy the contact resource names from the reviewed preview and scope both dry-run and apply to that exact set:

gog contacts dedupe \
  --resource people/123 \
  --resource people/456 \
  --apply \
  --dry-run \
  --json

Apply interactively:

gog contacts dedupe --apply

Non-interactive automation must explicitly skip confirmation:

gog contacts dedupe \
  --resource people/123 \
  --resource people/456 \
  --apply \
  --force \
  --json

Output

The command groups contacts that share a matching key. JSON output includes:

  • scanned: number of contacts examined
  • groups: likely duplicate groups
  • primary: the contact gog would keep first in a hypothetical merge plan
  • merged: merged emails/phones for preview
  • matched_on: duplicate email/phone/name keys that caused the group
  • members: all contacts in the group

Applied output also includes:

  • applied: whether mutations ran
  • groups_merged: groups completed
  • contacts_deleted: redundant contacts deleted
  • update_fields: People API fields unioned into the primary contact
  • delete: redundant contacts removed after their data was copied

Safety

contacts dedupe remains read-only unless --apply is present. Apply mode:

  • requires confirmation unless --force is present
  • honors --dry-run
  • supports repeatable --resource scoping so automation can apply an exact reviewed contact set
  • reads contact-source data only
  • refreshes each contact before planning
  • updates the selected primary before deleting anything
  • rechecks each redundant contact's etag immediately before deletion
  • refuses groups with conflicting singleton fields (names, birthdays, biographies, or genders)
  • refuses secondary contacts with photos or other fields the People API cannot preserve through updateContact

The People API does not expose Google Contacts' native merge operation. gog therefore unions all API-updatable fields into the selected primary, then deletes redundant contacts sequentially. If a request fails, the command stops and reports completed groups/deletions; copied data remains on the primary and undeleted contacts remain intact.

Use --fail-empty in scheduled checks when "no duplicates" should be reported as a distinct exit code:

gog contacts dedupe --fail-empty

Related Pages