path: root/Documentation/technical
diff options
Diffstat (limited to 'Documentation/technical')
8 files changed, 121 insertions, 244 deletions
diff --git a/Documentation/technical/api-argv-array.txt b/Documentation/technical/api-argv-array.txt
index 1a79781..8076172 100644
--- a/Documentation/technical/api-argv-array.txt
+++ b/Documentation/technical/api-argv-array.txt
@@ -46,6 +46,9 @@ Functions
Format a string and push it onto the end of the array. This is a
convenience wrapper combining `strbuf_addf` and `argv_array_push`.
+ Push a null-terminated array of strings onto the end of the array.
Remove the final element from the array. If there are no
elements in the array, do nothing.
diff --git a/Documentation/technical/api-lockfile.txt b/Documentation/technical/api-lockfile.txt
deleted file mode 100644
index 93b5f23..0000000
--- a/Documentation/technical/api-lockfile.txt
+++ /dev/null
@@ -1,220 +0,0 @@
-lockfile API
-The lockfile API serves two purposes:
-* Mutual exclusion and atomic file updates. When we want to change a
- file, we create a lockfile `<filename>.lock`, write the new file
- contents into it, and then rename the lockfile to its final
- destination `<filename>`. We create the `<filename>.lock` file with
- `O_CREAT|O_EXCL` so that we can notice and fail if somebody else has
- already locked the file, then atomically rename the lockfile to its
- final destination to commit the changes and unlock the file.
-* Automatic cruft removal. If the program exits after we lock a file
- but before the changes have been committed, we want to make sure
- that we remove the lockfile. This is done by remembering the
- lockfiles we have created in a linked list and setting up an
- `atexit(3)` handler and a signal handler that clean up the
- lockfiles. This mechanism ensures that outstanding lockfiles are
- cleaned up if the program exits (including when `die()` is called)
- or if the program dies on a signal.
-Please note that lockfiles only block other writers. Readers do not
-block, but they are guaranteed to see either the old contents of the
-file or the new contents of the file (assuming that the filesystem
-implements `rename(2)` atomically).
-Calling sequence
-The caller:
-* Allocates a `struct lock_file` either as a static variable or on the
- heap, initialized to zeros. Once you use the structure to call the
- `hold_lock_file_*` family of functions, it belongs to the lockfile
- subsystem and its storage must remain valid throughout the life of
- the program (i.e. you cannot use an on-stack variable to hold this
- structure).
-* Attempts to create a lockfile by passing that variable and the path
- of the final destination (e.g. `$GIT_DIR/index`) to
- `hold_lock_file_for_update` or `hold_lock_file_for_append`.
-* Writes new content for the destination file by either:
- * writing to the file descriptor returned by the `hold_lock_file_*`
- functions (also available via `lock->fd`).
- * calling `fdopen_lock_file` to get a `FILE` pointer for the open
- file and writing to the file using stdio.
-When finished writing, the caller can:
-* Close the file descriptor and rename the lockfile to its final
- destination by calling `commit_lock_file` or `commit_lock_file_to`.
-* Close the file descriptor and remove the lockfile by calling
- `rollback_lock_file`.
-* Close the file descriptor without removing or renaming the lockfile
- by calling `close_lock_file`, and later call `commit_lock_file`,
- `commit_lock_file_to`, `rollback_lock_file`, or `reopen_lock_file`.
-Even after the lockfile is committed or rolled back, the `lock_file`
-object must not be freed or altered by the caller. However, it may be
-reused; just pass it to another call of `hold_lock_file_for_update` or
-If the program exits before you have called one of `commit_lock_file`,
-`commit_lock_file_to`, `rollback_lock_file`, or `close_lock_file`, an
-`atexit(3)` handler will close and remove the lockfile, rolling back
-any uncommitted changes.
-If you need to close the file descriptor you obtained from a
-`hold_lock_file_*` function yourself, do so by calling
-`close_lock_file`. You should never call `close(2)` or `fclose(3)`
-yourself! Otherwise the `struct lock_file` structure would still think
-that the file descriptor needs to be closed, and a commit or rollback
-would result in duplicate calls to `close(2)`. Worse yet, if you close
-and then later open another file descriptor for a completely different
-purpose, then a commit or rollback might close that unrelated file
-Error handling
-The `hold_lock_file_*` functions return a file descriptor on success
-or -1 on failure (unless `LOCK_DIE_ON_ERROR` is used; see below). On
-errors, `errno` describes the reason for failure. Errors can be
-reported by passing `errno` to one of the following helper functions:
- Append an appropriate error message to a `strbuf`.
- Emit an appropriate error message using `error()`.
- Emit an appropriate error message and `die()`.
-Similarly, `commit_lock_file`, `commit_lock_file_to`, and
-`close_lock_file` return 0 on success. On failure they set `errno`
-appropriately, do their best to roll back the lockfile, and return -1.
-The following flags can be passed to `hold_lock_file_for_update` or
- Usually symbolic links in the destination path are resolved
- and the lockfile is created by adding ".lock" to the resolved
- path. If `LOCK_NO_DEREF` is set, then the lockfile is created
- by adding ".lock" to the path argument itself. This option is
- used, for example, when locking a symbolic reference, which
- for backwards-compatibility reasons can be a symbolic link
- containing the name of the referred-to-reference.
- If a lock is already taken for the file, `die()` with an error
- message. If this option is not specified, trying to lock a
- file that is already locked returns -1 to the caller.
-The functions
- Take a pointer to `struct lock_file`, the path of the file to
- be locked (e.g. `$GIT_DIR/index`) and a flags argument (see
- above). Attempt to create a lockfile for the destination and
- return the file descriptor for writing to the file.
- Like `hold_lock_file_for_update`, but before returning copy
- the existing contents of the file (if any) to the lockfile and
- position its write pointer at the end of the file.
- Associate a stdio stream with the lockfile. Return NULL
- (*without* rolling back the lockfile) on error. The stream is
- closed automatically when `close_lock_file` is called or when
- the file is committed or rolled back.
- Return the path of the file that is locked by the specified
- lock_file object. The caller must free the memory.
- Take a pointer to the `struct lock_file` initialized with an
- earlier call to `hold_lock_file_for_update` or
- `hold_lock_file_for_append`, close the file descriptor, and
- rename the lockfile to its final destination. Return 0 upon
- success. On failure, roll back the lock file and return -1,
- with `errno` set to the value from the failing call to
- `close(2)` or `rename(2)`. It is a bug to call
- `commit_lock_file` for a `lock_file` object that is not
- currently locked.
- Like `commit_lock_file()`, except that it takes an explicit
- `path` argument to which the lockfile should be renamed. The
- `path` must be on the same filesystem as the lock file.
- Take a pointer to the `struct lock_file` initialized with an
- earlier call to `hold_lock_file_for_update` or
- `hold_lock_file_for_append`, close the file descriptor and
- remove the lockfile. It is a NOOP to call
- `rollback_lock_file()` for a `lock_file` object that has
- already been committed or rolled back.
- Take a pointer to the `struct lock_file` initialized with an
- earlier call to `hold_lock_file_for_update` or
- `hold_lock_file_for_append`. Close the file descriptor (and
- the file pointer if it has been opened using
- `fdopen_lock_file`). Return 0 upon success. On failure to
- `close(2)`, return a negative value and roll back the lock
- file. Usually `commit_lock_file`, `commit_lock_file_to`, or
- `rollback_lock_file` should eventually be called if
- `close_lock_file` succeeds.
- Re-open a lockfile that has been closed (using
- `close_lock_file`) but not yet committed or rolled back. This
- can be used to implement a sequence of operations like the
- following:
- * Lock file.
- * Write new contents to lockfile, then `close_lock_file` to
- cause the contents to be written to disk.
- * Pass the name of the lockfile to another program to allow it
- (and nobody else) to inspect the contents you wrote, while
- still holding the lock yourself.
- * `reopen_lock_file` to reopen the lockfile. Make further
- updates to the contents.
- * `commit_lock_file` to make the final version permanent.
diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt
index 1f2db31..5f0757d 100644
--- a/Documentation/technical/api-parse-options.txt
+++ b/Documentation/technical/api-parse-options.txt
@@ -168,6 +168,12 @@ There are some macros to easily define options:
Introduce an option with integer argument.
The integer is put into `int_var`.
+`OPT_MAGNITUDE(short, long, &unsigned_long_var, description)`::
+ Introduce an option with a size argument. The argument must be a
+ non-negative integer and may include a suffix of 'k', 'm' or 'g' to
+ scale the provided value by 1024, 1024^2 or 1024^3 respectively.
+ The scaled value is put into `unsigned_long_var`.
`OPT_DATE(short, long, &int_var, description)`::
Introduce an option with date argument, see `approxidate()`.
The timestamp is put into `int_var`.
@@ -212,6 +218,19 @@ There are some macros to easily define options:
Use it to hide deprecated options that are still to be recognized
and ignored silently.
+`OPT_PASSTHRU(short, long, &char_var, arg_str, description, flags)`::
+ Introduce an option that will be reconstructed into a char* string,
+ which must be initialized to NULL. This is useful when you need to
+ pass the command-line option to another command. Any previous value
+ will be overwritten, so this should only be used for options where
+ the last one specified on the command line wins.
+`OPT_PASSTHRU_ARGV(short, long, &argv_array_var, arg_str, description, flags)`::
+ Introduce an option where all instances of it on the command-line will
+ be reconstructed into an argv_array. This is useful when you need to
+ pass the command-line option, which can be specified multiple times,
+ to another command.
The last element of the array must be `OPT_END()`.
diff --git a/Documentation/technical/api-submodule-config.txt b/Documentation/technical/api-submodule-config.txt
new file mode 100644
index 0000000..941fa17
--- /dev/null
+++ b/Documentation/technical/api-submodule-config.txt
@@ -0,0 +1,62 @@
+submodule config cache API
+The submodule config cache API allows to read submodule
+configurations/information from specified revisions. Internally
+information is lazily read into a cache that is used to avoid
+unnecessary parsing of the same .gitmodule files. Lookups can be done by
+submodule path or name.
+To initialize the cache with configurations from the worktree the caller
+typically first calls `gitmodules_config()` to read values from the
+worktree .gitmodules and then to overlay the local git config values
+`parse_submodule_config_option()` from the config parsing
+The caller can look up information about submodules by using the
+`submodule_from_path()` or `submodule_from_name()` functions. They return
+a `struct submodule` which contains the values. The API automatically
+initializes and allocates the needed infrastructure on-demand. If the
+caller does only want to lookup values from revisions the initialization
+can be skipped.
+If the internal cache might grow too big or when the caller is done with
+the API, all internally cached values can be freed with submodule_free().
+Data Structures
+`struct submodule`::
+ This structure is used to return the information about one
+ submodule for a certain revision. It is returned by the lookup
+ functions.
+`void submodule_free()`::
+ Use these to free the internally cached values.
+`int parse_submodule_config_option(const char *var, const char *value)`::
+ Can be passed to the config parsing infrastructure to parse
+ local (worktree) submodule configurations.
+`const struct submodule *submodule_from_path(const unsigned char *commit_sha1, const char *path)`::
+ Lookup values for one submodule by its commit_sha1 and path.
+`const struct submodule *submodule_from_name(const unsigned char *commit_sha1, const char *name)`::
+ The same as above but lookup by name.
+If given the null_sha1 as commit_sha1 the local configuration of a
+submodule will be returned (e.g. consolidated values from local git
+configuration and the .gitmodules file in the worktree).
+For an example usage see test-submodule-config.c.
diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt
index b7093af..7392ff6 100644
--- a/Documentation/technical/index-format.txt
+++ b/Documentation/technical/index-format.txt
@@ -275,7 +275,7 @@ Git index format
- The directory name terminated by NUL.
- - A number of untrached file/dir names terminated by NUL.
+ - A number of untracked file/dir names terminated by NUL.
The remaining data of each directory block is grouped by type:
diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt
index 4064fc7..c6977bb 100644
--- a/Documentation/technical/pack-protocol.txt
+++ b/Documentation/technical/pack-protocol.txt
@@ -14,6 +14,14 @@ data. The protocol functions to have a server tell a client what is
currently on the server, then for the two to negotiate the smallest amount
of data to send in order to fully update one or the other.
+pkt-line Format
+The descriptions below build on the pkt-line format described in
+protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless
+otherwise noted the usual pkt-line LF rules apply: the sender SHOULD
+include a LF, but the receiver MUST NOT complain if it is not present.
There are three transports over which the packfile protocol is
@@ -143,9 +151,6 @@ with the object name that each reference currently points to.
003fe92df48743b7bc7d26bcaabfddde0a1e20cae47c refs/tags/v1.0^{}
-Server SHOULD terminate each non-flush line using LF ("\n") terminator;
-client MUST NOT complain if there is no terminator.
The returned response is a pkt-line stream describing each ref and
its current value. The stream MUST be sorted by name according to
the C locale ordering.
@@ -165,15 +170,15 @@ MUST peel the ref if it's an annotated tag.
no-refs = PKT-LINE(zero-id SP "capabilities^{}"
- NUL capability-list LF)
+ NUL capability-list)
list-of-refs = first-ref *other-ref
first-ref = PKT-LINE(obj-id SP refname
- NUL capability-list LF)
+ NUL capability-list)
other-ref = PKT-LINE(other-tip / other-peeled)
- other-tip = obj-id SP refname LF
- other-peeled = obj-id SP refname "^{}" LF
+ other-tip = obj-id SP refname
+ other-peeled = obj-id SP refname "^{}"
shallow = PKT-LINE("shallow" SP obj-id)
@@ -216,8 +221,8 @@ out of what the server said it could do with the first 'want' line.
depth-request = PKT-LINE("deepen" SP depth)
- first-want = PKT-LINE("want" SP obj-id SP capability-list LF)
- additional-want = PKT-LINE("want" SP obj-id LF)
+ first-want = PKT-LINE("want" SP obj-id SP capability-list)
+ additional-want = PKT-LINE("want" SP obj-id)
depth = 1*DIGIT
@@ -284,7 +289,7 @@ so that there is always a block of 32 "in-flight on the wire" at a time.
have-list = *have-line
- have-line = PKT-LINE("have" SP obj-id LF)
+ have-line = PKT-LINE("have" SP obj-id)
compute-end = flush-pkt / PKT-LINE("done")
@@ -348,10 +353,10 @@ Then the server will start sending its packfile data.
server-response = *ack_multi ack / nak
- ack_multi = PKT-LINE("ACK" SP obj-id ack_status LF)
+ ack_multi = PKT-LINE("ACK" SP obj-id ack_status)
ack_status = "continue" / "common" / "ready"
- ack = PKT-LINE("ACK SP obj-id LF)
- nak = PKT-LINE("NAK" LF)
+ ack = PKT-LINE("ACK" SP obj-id)
+ nak = PKT-LINE("NAK")
A simple clone may look like this (with no 'have' lines):
@@ -467,10 +472,10 @@ references.
update-request = *shallow ( command-list | push-cert ) [packfile]
- shallow = PKT-LINE("shallow" SP obj-id LF)
+ shallow = PKT-LINE("shallow" SP obj-id)
- command-list = PKT-LINE(command NUL capability-list LF)
- *PKT-LINE(command LF)
+ command-list = PKT-LINE(command NUL capability-list)
+ *PKT-LINE(command)
command = create / delete / update
@@ -521,7 +526,8 @@ Push Certificate
A push certificate begins with a set of header lines. After the
header and an empty line, the protocol commands follow, one per
+line. Note that the the trailing LF in push-cert PKT-LINEs is _not_
+optional; it must be present.
Currently, the following header fields are defined:
@@ -560,12 +566,12 @@ update was successful, or 'ng [refname] [error]' if the update was not.
- unpack-status = PKT-LINE("unpack" SP unpack-result LF)
+ unpack-status = PKT-LINE("unpack" SP unpack-result)
unpack-result = "ok" / error-msg
command-status = command-ok / command-fail
- command-ok = PKT-LINE("ok" SP refname LF)
- command-fail = PKT-LINE("ng" SP refname SP error-msg LF)
+ command-ok = PKT-LINE("ok" SP refname)
+ command-fail = PKT-LINE("ng" SP refname SP error-msg)
error-msg = 1*(OCTECT) ; where not "ok"
diff --git a/Documentation/technical/protocol-common.txt b/Documentation/technical/protocol-common.txt
index 889985f..bf30167 100644
--- a/Documentation/technical/protocol-common.txt
+++ b/Documentation/technical/protocol-common.txt
@@ -62,7 +62,10 @@ A pkt-line MAY contain binary data, so implementors MUST ensure
pkt-line parsing/formatting routines are 8-bit clean.
A non-binary line SHOULD BE terminated by an LF, which if present
-MUST be included in the total length.
+MUST be included in the total length. Receivers MUST treat pkt-lines
+with non-binary data the same whether or not they contain the trailing
+LF (stripping the LF if present, and not complaining when it is
The maximum length of a pkt-line's data component is 65520 bytes.
Implementations MUST NOT send pkt-line whose length exceeds 65524
diff --git a/Documentation/technical/racy-git.txt b/Documentation/technical/racy-git.txt
index 242a044..4a8be4d 100644
--- a/Documentation/technical/racy-git.txt
+++ b/Documentation/technical/racy-git.txt
@@ -41,13 +41,17 @@ With a `USE_STDEV` compile-time option, `st_dev` is also
compared, but this is not enabled by default because this member
is not stable on network filesystems. With `USE_NSEC`
compile-time option, `st_mtim.tv_nsec` and `st_ctim.tv_nsec`
-members are also compared, but this is not enabled by default
+members are also compared. On Linux, this is not enabled by default
because in-core timestamps can have finer granularity than
on-disk timestamps, resulting in meaningless changes when an
inode is evicted from the inode cache. See commit 8ce13b0
of git://
([PATCH] Sync in core time granularity with filesystems,
+2005-01-04). This patch is included in kernel 2.6.11 and newer, but
+only fixes the issue for file systems with exactly 1 ns or 1 s
+resolution. Other file systems are still broken in current Linux
+kernels (e.g. CEPH, CIFS, NTFS, UDF), see
Racy Git