Follow how a piece of code changed.

Before you start

• Kin on your PATH, and a repository admitted with kin init. Admission brings the reachable Git history with it, so an entity has history from the first command.
• An author identity. Kin refuses to record a change it cannot attribute, so set git config user.name and user.email, or default_author in .kin/config.toml.
• An entity name. History is per entity, not per file: kin history takes a function or a module, and a name it cannot resolve is an error rather than an empty list.

The steps

1. 01

   Read what the entity already carries

   A freshly admitted repository has the history that came in with it. Each row is a semantic change, not a file revision.

   kin history formatAmount

   Copy command

   Compare with the saved example output

   History for 'formatAmount' (Function, javascript) at 61ad778d5479:
     61ad778d5479  2026-09-09  Docs Example  Add order pricing and receipt rendering

   One row per change that touched this entity, oldest first, with the change id, the date, the declared author and the message. Authorship is declared rather than checked, so read the author as a claim the change carries.

2. 02

   Change the entity

   Edit the source the way you normally would. Nothing is recorded yet, and kin status will say the tree is ahead of its base change.

   sed -n '1,4p' src/money.js

   Copy command

   Compare with the saved example output

   function formatAmount(cents, currency = 'USD') {
     const symbol = currency === 'USD' ? '$' : '';
     return `${symbol}${(cents / 100).toFixed(2)}`;
   }

   The new signature on disk. At this point the graph still answers from the last recorded change, which is why the next step matters.

3. 03

   Record the change in Kin

   This is the step people miss. A git commit moves Git; it does not record a semantic change, and Kin history is built from semantic changes.

   kin commit -m "Accept a currency argument when formatting an amount"

   Copy command

   Compare with the saved example output

   Created semantic change 5c15d027b9849974ea2b4d8e31ce8ce11ca3428d9bce65bac7d2d3a96fffd855 on branch 'refs/heads/main' (2 entities, 55 relations, 1 artifacts)

   A new change id and the entity, relation, and artifact counts it carries. The command also notes that the change is recorded in Kin rather than in Git, that git status remains uncommitted in Git, and provides guidance if you want Git moved instead.

4. 04

   Read the history again

   The same command, now with the change you just recorded.

   kin history formatAmount

   Copy command

   Compare with the saved example output

   History for 'formatAmount' (Function, javascript) at 5c15d027b984:
     61ad778d5479  2026-09-09  Docs Example  Add order pricing and receipt rendering
     5c15d027b984  2026-09-09  Docs Example  Accept a currency argument when formatting an amount

   Two rows. If you edited the file and committed with git instead, this list is still one row, because nothing recorded a semantic change. That is the single most common surprise on this page.

5. 05

   See what actually changed about the entity

   History says when. Blame says what the entity looked like at each revision, which is the question you usually had.

   kin blame formatAmount

   Copy command

   Compare with the saved example output

   2 version(s) found.
   
   State at 5c15d027b9849974ea2b4d8e31ce8ce11ca3428d9bce65bac7d2d3a96fffd855:
     Signature: function formatAmount(cents, currency = 'USD')
     Visibility: Private
     File: src/money.js

   A row per revision above this excerpt, then the state at the head change. The signature line is the fact most reviews want, and it is recorded rather than reconstructed from a diff.

6. 06

   Separate what came from Git from what Kin recorded

   The change log names the origin of every change, so an imported commit and a native change are never confused.

   kin log

   Copy command

   Compare with the saved example output

   change 5c15d027b9849974ea2b4d8e31ce8ce11ca3428d9bce65bac7d2d3a96fffd855
   Author: Docs Example <docs@example.com>
   Date:   2026-09-09T12:35:04.314887+00:00
   Origin: native
   Parents: 61ad778d54790180e31c78b2f1b6f8912d61fa0eb22eb049f70af07a46d8d865
   Deltas: entities=2 relations=55 tree=1 policy=false
       Accept a currency argument when formatting an amount
   
   change 61ad778d54790180e31c78b2f1b6f8912d61fa0eb22eb049f70af07a46d8d865
   Author: Docs Example <docs@example.com> 1788957227 -0400
   Date:   2026-09-09T12:33:47+00:00
   Origin: git commit 3fcc18849eea798f823e07a128900c9e6ef170df
   Deltas: entities=10 relations=19 tree=4 policy=true
       Add order pricing and receipt rendering

   Origin: native for a change Kin recorded, and Origin: git commit <sha> for one that came in with the import. A source fact and a recorded intent are different rows with different origins, and the log never merges them.

When the answer looks wrong

An empty or partial answer can reflect coverage, repository state, or an error. Each row below says what the state means and what to do next.

• Error: config error: kin has no author identity to record for this change.

  Kin will not attribute a change to nobody. Authorship is provenance, and a change recorded without it cannot be corrected later without rewriting history.

  Set git config user.name and user.email, or put default_author = "Your Name <you@example.com>" at the top of .kin/config.toml, above the first section.

• kin history refused (HTTP 500): No entity matching 'applyDiscount' found.

  The name did not resolve to an entity in this repository.

  Run kin search applyDiscount to find the real name, then ask again.

• History shows one row after you changed and committed the file.

  The commit went to Git. Kin history is built from semantic changes, and a git commit does not create one.

  Record the change with kin commit, then read the history again.

• git status stays dirty after kin commit.

  That is what the command says it does. The change is recorded in Kin authority, and Git has not been moved.

  Leave it, push the branch to a Kin remote, or run the detach command the message names, which installs exact Git and steps Kin out of the way. Read what kin commit printed before you pick one.