[thirdparty/git.git] / Documentation / technical / shallow.txt

Shallow commits
===============

.Definition
*********************************************************
Shallow commits do have parents, but not in the shallow
repo, and therefore grafts are introduced pretending that
these commits have no parents.
*********************************************************

$GIT_DIR/shallow lists commit object names and tells Git to
pretend as if they are root commits (e.g. "git log" traversal
stops after showing them; "git fsck" does not complain saying
the commits listed on their "parent" lines do not exist).

Each line contains exactly one object name. When read, a commit_graft
will be constructed, which has nr_parent < 0 to make it easier
to discern from user provided grafts.

Note that the shallow feature could not be changed easily to
use replace refs: a commit containing a `mergetag` is not allowed
to be replaced, not even by a root commit. Such a commit can be
made shallow, though. Also, having a `shallow` file explicitly
listing all the commits made shallow makes it a *lot* easier to
do shallow-specific things such as to deepen the history.

Since fsck-objects relies on the library to read the objects,
it honours shallow commits automatically.

There are some unfinished ends of the whole shallow business:

- maybe we have to force non-thin packs when fetching into a
  shallow repo (ATM they are forced non-thin).

- A special handling of a shallow upstream is needed. At some
  stage, upload-pack has to check if it sends a shallow commit,
  and it should send that information early (or fail, if the
  client does not support shallow repositories). There is no
  support at all for this in this patch series.

- Instead of locking $GIT_DIR/shallow at the start, just
  the timestamp of it is noted, and when it comes to writing it,
  a check is performed if the mtime is still the same, dying if
  it is not.

- It is unclear how "push into/from a shallow repo" should behave.

- If you deepen a history, you'd want to get the tags of the
  newly stored (but older!) commits. This does not work right now.

To make a shallow clone, you can call "git-clone --depth 20 repo".
The result contains only commit chains with a length of at most 20.
It also writes an appropriate $GIT_DIR/shallow.

You can deepen a shallow repository with "git-fetch --depth 20
repo branch", which will fetch branch from repo, but stop at depth
20, updating $GIT_DIR/shallow.

The special depth 2147483647 (or 0x7fffffff, the largest positive
number a signed 32-bit integer can contain) means infinite depth.
Commit	Line	Data
5316c8e9 TA	1	Shallow commits
	2	===============
	3
	4	.Definition
	5	*********************************************************
	6	Shallow commits do have parents, but not in the shallow
1b89ef17 JS	7	repo, and therefore grafts are introduced pretending that
1b89ef17 JS	8	these commits have no parents.
5316c8e9	9	*********************************************************
1b89ef17	10
8d0d81a9 JS	11	$GIT_DIR/shallow lists commit object names and tells Git to
	12	pretend as if they are root commits (e.g. "git log" traversal
	13	stops after showing them; "git fsck" does not complain saying
	14	the commits listed on their "parent" lines do not exist).
1b89ef17	15
8afa50aa	16	Each line contains exactly one object name. When read, a commit_graft
1b89ef17 JS	17	will be constructed, which has nr_parent < 0 to make it easier
	18	to discern from user provided grafts.
	19
f42fa470 JS	20	Note that the shallow feature could not be changed easily to
	21	use replace refs: a commit containing a `mergetag` is not allowed
	22	to be replaced, not even by a root commit. Such a commit can be
	23	made shallow, though. Also, having a `shallow` file explicitly
	24	listing all the commits made shallow makes it a lot easier to
	25	do shallow-specific things such as to deepen the history.
	26
1b89ef17 JS	27	Since fsck-objects relies on the library to read the objects,
	28	it honours shallow commits automatically.
	29
	30	There are some unfinished ends of the whole shallow business:
	31
	32	- maybe we have to force non-thin packs when fetching into a
	33	shallow repo (ATM they are forced non-thin).
	34
	35	- A special handling of a shallow upstream is needed. At some
	36	stage, upload-pack has to check if it sends a shallow commit,
	37	and it should send that information early (or fail, if the
	38	client does not support shallow repositories). There is no
	39	support at all for this in this patch series.
	40
	41	- Instead of locking $GIT_DIR/shallow at the start, just
	42	the timestamp of it is noted, and when it comes to writing it,
	43	a check is performed if the mtime is still the same, dying if
	44	it is not.
	45
	46	- It is unclear how "push into/from a shallow repo" should behave.
	47
	48	- If you deepen a history, you'd want to get the tags of the
	49	newly stored (but older!) commits. This does not work right now.
	50
	51	To make a shallow clone, you can call "git-clone --depth 20 repo".
	52	The result contains only commit chains with a length of at most 20.
	53	It also writes an appropriate $GIT_DIR/shallow.
	54
	55	You can deepen a shallow repository with "git-fetch --depth 20
	56	repo branch", which will fetch branch from repo, but stop at depth
	57	20, updating $GIT_DIR/shallow.
4dcb167f NTND	58
	59	The special depth 2147483647 (or 0x7fffffff, the largest positive
	60	number a signed 32-bit integer can contain) means infinite depth.