summaryrefslogtreecommitdiff
path: root/Documentation/technical
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/technical')
-rw-r--r--Documentation/technical/api-builtin.txt4
-rw-r--r--Documentation/technical/api-config.txt10
-rw-r--r--Documentation/technical/api-credentials.txt20
-rw-r--r--Documentation/technical/api-directory-listing.txt37
-rw-r--r--Documentation/technical/api-index-skel.txt4
-rw-r--r--Documentation/technical/api-parse-options.txt2
-rw-r--r--Documentation/technical/api-remote.txt4
-rw-r--r--Documentation/technical/api-strbuf.txt10
-rw-r--r--Documentation/technical/index-format.txt8
-rw-r--r--Documentation/technical/pack-format.txt4
-rw-r--r--Documentation/technical/pack-heuristics.txt20
-rw-r--r--Documentation/technical/racy-git.txt26
-rw-r--r--Documentation/technical/shallow.txt3
13 files changed, 86 insertions, 66 deletions
diff --git a/Documentation/technical/api-builtin.txt b/Documentation/technical/api-builtin.txt
index b0cafe87be..4a4228b896 100644
--- a/Documentation/technical/api-builtin.txt
+++ b/Documentation/technical/api-builtin.txt
@@ -5,7 +5,7 @@ Adding a new built-in
---------------------
There are 4 things to do to add a built-in command implementation to
-git:
+Git:
. Define the implementation of the built-in command `foo` with
signature:
@@ -23,7 +23,7 @@ where options is the bitwise-or of:
`RUN_SETUP`::
- Make sure there is a git directory to work on, and if there is a
+ Make sure there is a Git directory to work on, and if there is a
work tree, chdir to the top of it if the command was invoked
in a subdirectory. If there is no work tree, no chdir() is
done.
diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt
index edf8dfb99b..230b3a0f60 100644
--- a/Documentation/technical/api-config.txt
+++ b/Documentation/technical/api-config.txt
@@ -1,7 +1,7 @@
config API
==========
-The config API gives callers a way to access git configuration files
+The config API gives callers a way to access Git configuration files
(and files which have the same syntax). See linkgit:git-config[1] for a
discussion of the config file syntax.
@@ -12,7 +12,7 @@ Config files are parsed linearly, and each variable found is passed to a
caller-provided callback function. The callback function is responsible
for any actions to be taken on the config option, and is free to ignore
some options. It is not uncommon for the configuration to be parsed
-several times during the run of a git program, with different callbacks
+several times during the run of a Git program, with different callbacks
picking out different variables useful to themselves.
A config callback function takes three parameters:
@@ -36,7 +36,7 @@ Basic Config Querying
---------------------
Most programs will simply want to look up variables in all config files
-that git knows about, using the normal precedence rules. To do this,
+that Git knows about, using the normal precedence rules. To do this,
call `git_config` with a callback function and void data pointer.
`git_config` will read all config sources in order of increasing
@@ -49,7 +49,7 @@ value is left at the end).
The `git_config_with_options` function lets the caller examine config
while adjusting some of the default behavior of `git_config`. It should
-almost never be used by "regular" git code that is looking up
+almost never be used by "regular" Git code that is looking up
configuration variables. It is intended for advanced callers like
`git-config`, which are intentionally tweaking the normal config-lookup
process. It takes two extra parameters:
@@ -66,7 +66,7 @@ Regular `git_config` defaults to `1`.
There is a special version of `git_config` called `git_config_early`.
This version takes an additional parameter to specify the repository
config, instead of having it looked up via `git_path`. This is useful
-early in a git program before the repository has been found. Unless
+early in a Git program before the repository has been found. Unless
you're working with early setup code, you probably don't want to use
this.
diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt
index 5977b58e57..516fda7412 100644
--- a/Documentation/technical/api-credentials.txt
+++ b/Documentation/technical/api-credentials.txt
@@ -7,9 +7,9 @@ world can take many forms, in this document the word "credential" always
refers to a username and password pair).
This document describes two interfaces: the C API that the credential
-subsystem provides to the rest of git, and the protocol that git uses to
+subsystem provides to the rest of Git, and the protocol that Git uses to
communicate with system-specific "credential helpers". If you are
-writing git code that wants to look up or prompt for credentials, see
+writing Git code that wants to look up or prompt for credentials, see
the section "C API" below. If you want to write your own helper, see
the section on "Credential Helpers" below.
@@ -18,7 +18,7 @@ Typical setup
------------
+-----------------------+
-| git code (C) |--- to server requiring --->
+| Git code (C) |--- to server requiring --->
| | authentication
|.......................|
| C credential API |--- prompt ---> User
@@ -27,11 +27,11 @@ Typical setup
| pipe |
| v
+-----------------------+
-| git credential helper |
+| Git credential helper |
+-----------------------+
------------
-The git code (typically a remote-helper) will call the C API to obtain
+The Git code (typically a remote-helper) will call the C API to obtain
credential data like a login/password pair (credential_fill). The
API will itself call a remote helper (e.g. "git credential-cache" or
"git credential-store") that may retrieve credential data from a
@@ -42,7 +42,7 @@ contacting the server, and does the actual authentication.
C API
-----
-The credential C API is meant to be called by git code which needs to
+The credential C API is meant to be called by Git code which needs to
acquire or store a credential. It is centered around an object
representing a single credential and provides three basic operations:
fill (acquire credentials by calling helpers and/or prompting the user),
@@ -177,14 +177,14 @@ int foo_login(struct foo_connection *f)
Credential Helpers
------------------
-Credential helpers are programs executed by git to fetch or save
+Credential helpers are programs executed by Git to fetch or save
credentials from and to long-term storage (where "long-term" is simply
-longer than a single git process; e.g., credentials may be stored
+longer than a single Git process; e.g., credentials may be stored
in-memory for a few minutes, or indefinitely on disk).
Each helper is specified by a single string in the configuration
variable `credential.helper` (and others, see linkgit:git-config[1]).
-The string is transformed by git into a command to be executed using
+The string is transformed by Git into a command to be executed using
these rules:
1. If the helper string begins with "!", it is considered a shell
@@ -248,7 +248,7 @@ FORMAT` in linkgit:git-credential[7] for a detailed specification).
For a `get` operation, the helper should produce a list of attributes
on stdout in the same format. A helper is free to produce a subset, or
even no values at all if it has nothing useful to provide. Any provided
-attributes will overwrite those already known about by git.
+attributes will overwrite those already known about by Git.
For a `store` or `erase` operation, the helper's output is ignored.
If it fails to perform the requested operation, it may complain to
diff --git a/Documentation/technical/api-directory-listing.txt b/Documentation/technical/api-directory-listing.txt
index add6f435b5..1f349b28ae 100644
--- a/Documentation/technical/api-directory-listing.txt
+++ b/Documentation/technical/api-directory-listing.txt
@@ -9,37 +9,40 @@ Data structure
--------------
`struct dir_struct` structure is used to pass directory traversal
-options to the library and to record the paths discovered. The notable
-options are:
+options to the library and to record the paths discovered. A single
+`struct dir_struct` is used regardless of whether or not the traversal
+recursively descends into subdirectories.
+
+The notable options are:
`exclude_per_dir`::
The name of the file to be read in each directory for excluded
files (typically `.gitignore`).
-`collect_ignored`::
+`flags`::
- Include paths that are to be excluded in the result.
+ A bit-field of options:
-`show_ignored`::
+`DIR_SHOW_IGNORED`:::
The traversal is for finding just ignored files, not unignored
files.
-`show_other_directories`::
+`DIR_SHOW_OTHER_DIRECTORIES`:::
Include a directory that is not tracked.
-`hide_empty_directories`::
+`DIR_HIDE_EMPTY_DIRECTORIES`:::
Do not include a directory that is not tracked and is empty.
-`no_gitlinks`::
+`DIR_NO_GITLINKS`:::
- If set, recurse into a directory that looks like a git
+ If set, recurse into a directory that looks like a Git
directory. Otherwise it is shown as a directory.
-The result of the enumeration is left in these fields::
+The result of the enumeration is left in these fields:
`entries[]`::
@@ -64,11 +67,13 @@ marked. If you to exclude files, make sure you have loaded index first.
* Prepare `struct dir_struct dir` and clear it with `memset(&dir, 0,
sizeof(dir))`.
-* Call `add_exclude()` to add single exclude pattern,
- `add_excludes_from_file()` to add patterns from a file
- (e.g. `.git/info/exclude`), and/or set `dir.exclude_per_dir`. A
- short-hand function `setup_standard_excludes()` can be used to set up
- the standard set of exclude settings.
+* To add single exclude pattern, call `add_exclude_list()` and then
+ `add_exclude()`.
+
+* To add patterns from a file (e.g. `.git/info/exclude`), call
+ `add_excludes_from_file()` , and/or set `dir.exclude_per_dir`. A
+ short-hand function `setup_standard_excludes()` can be used to set
+ up the standard set of exclude settings.
* Set options described in the Data Structure section above.
@@ -76,4 +81,6 @@ marked. If you to exclude files, make sure you have loaded index first.
* Use `dir.entries[]`.
+* Call `clear_directory()` when none of the contained elements are no longer in use.
+
(JC)
diff --git a/Documentation/technical/api-index-skel.txt b/Documentation/technical/api-index-skel.txt
index 730cfacf78..eda8c195c1 100644
--- a/Documentation/technical/api-index-skel.txt
+++ b/Documentation/technical/api-index-skel.txt
@@ -1,7 +1,7 @@
-GIT API Documents
+Git API Documents
=================
-GIT has grown a set of internal API over time. This collection
+Git has grown a set of internal API over time. This collection
documents them.
////////////////////////////////////////////////////////////////
diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt
index 3062389404..32ddc1cf13 100644
--- a/Documentation/technical/api-parse-options.txt
+++ b/Documentation/technical/api-parse-options.txt
@@ -1,7 +1,7 @@
parse-options API
=================
-The parse-options API is used to parse and massage options in git
+The parse-options API is used to parse and massage options in Git
and to provide a usage help with consistent look.
Basics
diff --git a/Documentation/technical/api-remote.txt b/Documentation/technical/api-remote.txt
index c54b17db69..4be87768f6 100644
--- a/Documentation/technical/api-remote.txt
+++ b/Documentation/technical/api-remote.txt
@@ -3,7 +3,7 @@ Remotes configuration API
The API in remote.h gives access to the configuration related to
remotes. It handles all three configuration mechanisms historically
-and currently used by git, and presents the information in a uniform
+and currently used by Git, and presents the information in a uniform
fashion. Note that the code also handles plain URLs without any
configuration, giving them just the default information.
@@ -45,7 +45,7 @@ struct remote
`receivepack`, `uploadpack`::
The configured helper programs to run on the remote side, for
- git-native protocols.
+ Git-native protocols.
`http_proxy`::
diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt
index 84686b5c69..2c59cb2259 100644
--- a/Documentation/technical/api-strbuf.txt
+++ b/Documentation/technical/api-strbuf.txt
@@ -156,6 +156,11 @@ then they will free() it.
Remove the bytes between `pos..pos+len` and replace it with the given
data.
+`strbuf_add_commented_lines`::
+
+ Add a NUL-terminated string to the buffer. Each line will be prepended
+ by a comment character and a blank.
+
`strbuf_add`::
Add data of given length to the buffer.
@@ -229,6 +234,11 @@ which can be used by the programmer of the callback as she sees fit.
Add a formatted string to the buffer.
+`strbuf_commented_addf`::
+
+ Add a formatted string prepended by a comment character and a
+ blank to the buffer.
+
`strbuf_fread`::
Read a given size of data from a FILE* pointer to the buffer.
diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt
index 7324154838..27c716b15f 100644
--- a/Documentation/technical/index-format.txt
+++ b/Documentation/technical/index-format.txt
@@ -1,7 +1,7 @@
-GIT index format
+Git index format
================
-== The git index file has the following format
+== The Git index file has the following format
All binary numbers are in network byte order. Version 2 is described
here unless stated otherwise.
@@ -21,9 +21,9 @@ GIT index format
- Extensions
Extensions are identified by signature. Optional extensions can
- be ignored if GIT does not understand them.
+ be ignored if Git does not understand them.
- GIT currently supports cached tree and resolve undo extensions.
+ Git currently supports cached tree and resolve undo extensions.
4-byte extension signature. If the first byte is 'A'..'Z' the
extension is optional and can be ignored.
diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt
index a7871fb865..0e37ec9de5 100644
--- a/Documentation/technical/pack-format.txt
+++ b/Documentation/technical/pack-format.txt
@@ -1,4 +1,4 @@
-GIT pack format
+Git pack format
===============
== pack-*.pack files have the following format:
@@ -9,7 +9,7 @@ GIT pack format
The signature is: {'P', 'A', 'C', 'K'}
4-byte version number (network byte order):
- GIT currently accepts version number 2 or 3 but
+ Git currently accepts version number 2 or 3 but
generates version 2 only.
4-byte number of objects contained in the pack (network byte order)
diff --git a/Documentation/technical/pack-heuristics.txt b/Documentation/technical/pack-heuristics.txt
index 103eb5d989..dbdf7ba9c8 100644
--- a/Documentation/technical/pack-heuristics.txt
+++ b/Documentation/technical/pack-heuristics.txt
@@ -5,11 +5,11 @@
Where do I go
to learn the details
- of git's packing heuristics?
+ of Git's packing heuristics?
Be careful what you ask!
-Followers of the git, please open the git IRC Log and turn to
+Followers of the Git, please open the Git IRC Log and turn to
February 10, 2006.
It's a rare occasion, and we are joined by the King Git Himself,
@@ -19,7 +19,7 @@ and seeks enlightenment. Others are present, but silent.
Let's listen in!
<njs`> Oh, here's a really stupid question -- where do I go to
- learn the details of git's packing heuristics? google avails
+ learn the details of Git's packing heuristics? google avails
me not, reading the source didn't help a lot, and wading
through the whole mailing list seems less efficient than any
of that.
@@ -37,7 +37,7 @@ Ah! Modesty after all.
<linus> njs, I don't think the docs exist. That's something where
I don't think anybody else than me even really got involved.
- Most of the rest of git others have been busy with (especially
+ Most of the rest of Git others have been busy with (especially
Junio), but packing nobody touched after I did it.
It's cryptic, yet vague. Linus in style for sure. Wise men
@@ -57,7 +57,7 @@ Bait...
And switch. That ought to do it!
- <linus> Remember: git really doesn't follow files. So what it does is
+ <linus> Remember: Git really doesn't follow files. So what it does is
- generate a list of all objects
- sort the list according to magic heuristics
- walk the list, using a sliding window, seeing if an object
@@ -382,7 +382,7 @@ The 'net never forgets, so that should be good until the end of time.
<njs`> (if only it happened more...)
<linus> Anyway, the pack-file could easily be denser still, but
- because it's used both for streaming (the git protocol) and
+ because it's used both for streaming (the Git protocol) and
for on-disk, it has a few pessimizations.
Actually, it is a made-up word. But it is a made-up word being
@@ -432,12 +432,12 @@ Gasp! OK, saved. That's a fair Engineering trade off. Close call!
In fact, Linus reflects on some Basic Engineering Fundamentals,
design options, etc.
- <linus> More importantly, they allow git to still _conceptually_
+ <linus> More importantly, they allow Git to still _conceptually_
never deal with deltas at all, and be a "whole object" store.
Which has some problems (we discussed bad huge-file
- behaviour on the git lists the other day), but it does mean
- that the basic git concepts are really really simple and
+ behaviour on the Git lists the other day), but it does mean
+ that the basic Git concepts are really really simple and
straightforward.
It's all been quite stable.
@@ -461,6 +461,6 @@ Nuff said.
<njs`> :-)
<njs`> appreciate the infodump, I really was failing to find the
- details on git packs :-)
+ details on Git packs :-)
And now you know the rest of the story.
diff --git a/Documentation/technical/racy-git.txt b/Documentation/technical/racy-git.txt
index 53aa0c82c2..6dc82ca5a8 100644
--- a/Documentation/technical/racy-git.txt
+++ b/Documentation/technical/racy-git.txt
@@ -1,21 +1,21 @@
-Use of index and Racy git problem
+Use of index and Racy Git problem
=================================
Background
----------
-The index is one of the most important data structures in git.
+The index is one of the most important data structures in Git.
It represents a virtual working tree state by recording list of
paths and their object names and serves as a staging area to
write out the next tree object to be committed. The state is
"virtual" in the sense that it does not necessarily have to, and
often does not, match the files in the working tree.
-There are cases git needs to examine the differences between the
+There are cases Git needs to examine the differences between the
virtual working tree state in the index and the files in the
working tree. The most obvious case is when the user asks `git
diff` (or its low level implementation, `git diff-files`) or
-`git-ls-files --modified`. In addition, git internally checks
+`git-ls-files --modified`. In addition, Git internally checks
if the files in the working tree are different from what are
recorded in the index to avoid stomping on local changes in them
during patch application, switching branches, and merging.
@@ -24,16 +24,16 @@ In order to speed up this comparison between the files in the
working tree and the index entries, the index entries record the
information obtained from the filesystem via `lstat(2)` system
call when they were last updated. When checking if they differ,
-git first runs `lstat(2)` on the files and compares the result
+Git first runs `lstat(2)` on the files and compares the result
with this information (this is what was originally done by the
`ce_match_stat()` function, but the current code does it in
`ce_match_stat_basic()` function). If some of these "cached
-stat information" fields do not match, git can tell that the
+stat information" fields do not match, Git can tell that the
files are modified without even looking at their contents.
Note: not all members in `struct stat` obtained via `lstat(2)`
are used for this comparison. For example, `st_atime` obviously
-is not useful. Currently, git compares the file type (regular
+is not useful. Currently, Git compares the file type (regular
files vs symbolic links) and executable bits (only for regular
files) from `st_mode` member, `st_mtime` and `st_ctime`
timestamps, `st_uid`, `st_gid`, `st_ino`, and `st_size` members.
@@ -49,7 +49,7 @@ of git://git.kernel.org/pub/scm/linux/kernel/git/tglx/history.git
([PATCH] Sync in core time granuality with filesystems,
2005-01-04).
-Racy git
+Racy Git
--------
There is one slight problem with the optimization based on the
@@ -67,13 +67,13 @@ timestamp does not change, after this sequence, the cached stat
information the index entry records still exactly match what you
would see in the filesystem, even though the file `foo` is now
different.
-This way, git can incorrectly think files in the working tree
+This way, Git can incorrectly think files in the working tree
are unmodified even though they actually are. This is called
-the "racy git" problem (discovered by Pasky), and the entries
+the "racy Git" problem (discovered by Pasky), and the entries
that appear clean when they may not be because of this problem
are called "racily clean".
-To avoid this problem, git does two things:
+To avoid this problem, Git does two things:
. When the cached stat information says the file has not been
modified, and the `st_mtime` is the same as (or newer than)
@@ -116,7 +116,7 @@ timestamp comparison check done with the former logic anymore.
The latter makes sure that the cached stat information for `foo`
would never match with the file in the working tree, so later
checks by `ce_match_stat_basic()` would report that the index entry
-does not match the file and git does not have to fall back on more
+does not match the file and Git does not have to fall back on more
expensive `ce_modified_check_fs()`.
@@ -159,7 +159,7 @@ of the cached stat information.
Avoiding runtime penalty
------------------------
-In order to avoid the above runtime penalty, post 1.4.2 git used
+In order to avoid the above runtime penalty, post 1.4.2 Git used
to have a code that made sure the index file
got timestamp newer than the youngest files in the index when
there are many young files with the same timestamp as the
diff --git a/Documentation/technical/shallow.txt b/Documentation/technical/shallow.txt
index 0502a5471e..ea2f69faf5 100644
--- a/Documentation/technical/shallow.txt
+++ b/Documentation/technical/shallow.txt
@@ -53,3 +53,6 @@ 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.