diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/RelNotes/2.31.0.txt | 59 | ||||
| -rw-r--r-- | Documentation/SubmittingPatches | 2 | ||||
| -rw-r--r-- | Documentation/config/core.txt | 2 | ||||
| -rw-r--r-- | Documentation/config/diff.txt | 2 | ||||
| -rw-r--r-- | Documentation/config/http.txt | 4 | ||||
| -rw-r--r-- | Documentation/config/trace2.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-clone.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-ls-files.txt | 5 | ||||
| -rw-r--r-- | Documentation/git-maintenance.txt | 118 | ||||
| -rw-r--r-- | Documentation/git-mktag.txt | 39 | ||||
| -rw-r--r-- | Documentation/git-p4.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-rev-parse.txt | 74 | ||||
| -rw-r--r-- | Documentation/git-send-email.txt | 6 | ||||
| -rw-r--r-- | Documentation/git-status.txt | 28 | ||||
| -rw-r--r-- | Documentation/git-update-index.txt | 5 | ||||
| -rw-r--r-- | Documentation/githooks.txt | 2 | ||||
| -rw-r--r-- | Documentation/gitmodules.txt | 30 | ||||
| -rw-r--r-- | Documentation/technical/pack-format.txt | 17 | ||||
| -rw-r--r-- | Documentation/technical/reftable.txt | 2 |
19 files changed, 328 insertions, 75 deletions
diff --git a/Documentation/RelNotes/2.31.0.txt b/Documentation/RelNotes/2.31.0.txt index 6bde597b2d..47041f3376 100644 --- a/Documentation/RelNotes/2.31.0.txt +++ b/Documentation/RelNotes/2.31.0.txt @@ -17,16 +17,75 @@ UI, Workflows & Features no reason to stop or force the user to choose between rebase or merge if the history fast-forwards. + * The configuration variable 'core.abbrev' can be set to 'no' to + force no abbreviation regardless of the hash algorithm. + + * "git rev-parse" can be explicitly told to give output as absolute + or relative path with the `--path-format=(absolute|relative)` option. + + * Bash completion (in contrib/) update to make it easier for + end-users to add completion for their custom "git" subcommands. + + * "git maintenance" learned to drive scheduled maintenance on + platforms whose native scheduling methods are not 'cron'. + Performance, Internal Implementation, Development Support etc. * A 3-year old test that was not testing anything useful has been corrected. + * Retire more names with "sha1" in it. + + * The topological walk codepath is covered by new trace2 stats. + Fixes since v2.30 ----------------- + * Diagnose command line error of "git rebase" early. + (merge ca5120c339 rs/rebase-commit-validation later to maint). + + * Clean up option descriptions in "git cmd --help". + (merge e73fe3dd02 zh/arg-help-format later to maint). + + * "git stash" did not work well in a sparsely checked out working + tree. + (merge ba359fd507 en/stash-apply-sparse-checkout later to maint). + + * Some tests expect that "ls -l" output has either '-' or 'x' for + group executable bit, but setgid bit can be inherited from parent + directory and make these fields 'S' or 's' instead, causing test + failures. + (merge ea8bbf2a4e mt/t4129-with-setgid-dir later to maint). + + * "git for-each-repo --config=<var> <cmd>" should not run <cmd> for + any repository when the configuration variable <var> is not defined + even once. + (merge 6c62f01552 ds/for-each-repo-noopfix later to maint). + + * Fix 2.29 regression where "git mergetool --tool-help" fails to list + all the available tools. + (merge 80f5a16798 pb/mergetool-tool-help-fix later to maint). + + * Fix for procedure to building CI test environment for mac. + (merge 3831132ace jc/macos-install-dependencies-fix later to maint). + * Other code cleanup, docfix, build fix, etc. (merge 505a276596 pk/subsub-fetch-fix-take-2 later to maint). (merge 33fc56253b fc/t6030-bisect-reset-removes-auxiliary-files later to maint). + (merge 7efc378205 ta/doc-typofix later to maint). + (merge 1f4e9319c7 pb/doc-modules-git-work-tree-typofix later to maint). + (merge 04f6b0a192 ma/t1300-cleanup later to maint). + (merge 7b77f5a13e ma/doc-pack-format-varint-for-sizes later to maint). + (merge cc2d43be2b nk/perf-fsmonitor-cleanup later to maint). + (merge c8302c6c00 ar/t6016-modernise later to maint). + (merge 0454986e78 jc/sign-off later to maint). + (merge 155067ab4f vv/send-email-with-less-secure-apps-access later to maint). + (merge acaabcf391 jk/t5516-deflake later to maint). + (merge a1e03535db ad/t4129-setfacl-target-fix later to maint). + (merge b356d23638 ug/doc-lose-dircache later to maint). + (merge 9371c0e9dd ab/gettext-charset-comment-fix later to maint). + (merge 52fc4f195c dl/p4-encode-after-kw-expansion later to maint). + (merge 4eb56b56e7 bc/doc-status-short later to maint). + (merge a4a1ca22ef tb/local-clone-race-doc later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index d12094bac5..0452db2e67 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -307,7 +307,7 @@ wrote the patch or have the right to pass it on under the same license as ours, by "signing off" your patch. Without sign-off, we cannot accept your patches. -If you can certify the below D-C-O: +If (and only if) you certify the below D-C-O: [[dco]] .Developer's Certificate of Origin 1.1 diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt index 160aacad84..c04f62a54a 100644 --- a/Documentation/config/core.txt +++ b/Documentation/config/core.txt @@ -625,4 +625,6 @@ core.abbrev:: computed based on the approximate number of packed objects in your repository, which hopefully is enough for abbreviated object names to stay unique for some time. + If set to "no", no abbreviation is made and the object names + are shown in their full length. The minimum length is 4. diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt index c3ae136eba..2d3331f55c 100644 --- a/Documentation/config/diff.txt +++ b/Documentation/config/diff.txt @@ -85,6 +85,8 @@ diff.ignoreSubmodules:: and 'git status' when `status.submoduleSummary` is set unless it is overridden by using the --ignore-submodules command-line option. The 'git submodule' commands are not affected by this setting. + By default this is set to untracked so that any untracked + submodules are ignored. diff.mnemonicPrefix:: If set, 'git diff' uses a prefix pair that is different from the diff --git a/Documentation/config/http.txt b/Documentation/config/http.txt index 3968fbb697..7003661c0d 100644 --- a/Documentation/config/http.txt +++ b/Documentation/config/http.txt @@ -42,12 +42,12 @@ http.proxySSLKey:: http.proxySSLCertPasswordProtected:: Enable Git's password prompt for the proxy SSL certificate. Otherwise OpenSSL will prompt the user, possibly many times, if the certificate or private key - is encrypted. Can be overriden by the `GIT_PROXY_SSL_CERT_PASSWORD_PROTECTED` + is encrypted. Can be overridden by the `GIT_PROXY_SSL_CERT_PASSWORD_PROTECTED` environment variable. http.proxySSLCAInfo:: Pathname to the file containing the certificate bundle that should be used to - verify the proxy with when using an HTTPS proxy. Can be overriden by the + verify the proxy with when using an HTTPS proxy. Can be overridden by the `GIT_PROXY_SSL_CAINFO` environment variable. http.emptyAuth:: diff --git a/Documentation/config/trace2.txt b/Documentation/config/trace2.txt index 01d3afd8a8..fe1642f0d4 100644 --- a/Documentation/config/trace2.txt +++ b/Documentation/config/trace2.txt @@ -54,7 +54,7 @@ trace2.envVars:: `GIT_HTTP_USER_AGENT,GIT_CONFIG` would cause the trace2 output to contain events listing the overrides for HTTP user agent and the location of the Git configuration file (assuming any are set). May be - overriden by the `GIT_TRACE2_ENV_VARS` environment variable. Unset by + overridden by the `GIT_TRACE2_ENV_VARS` environment variable. Unset by default. trace2.destinationDebug:: diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 876aedcd47..02d9c19cec 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -57,6 +57,10 @@ repository is specified as a URL, then this flag is ignored (and we never use the local optimizations). Specifying `--no-local` will override the default when `/path/to/repo` is given, using the regular Git transport instead. ++ +*NOTE*: this operation can race with concurrent modification to the +source repository, similar to running `cp -r src dst` while modifying +`src`. --no-hardlinks:: Force the cloning process from a repository on a local diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index cbcf5263dd..0a3b5265b3 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -23,9 +23,8 @@ SYNOPSIS DESCRIPTION ----------- -This merges the file listing in the directory cache index with the -actual working directory list, and shows different combinations of the -two. +This merges the file listing in the index with the actual working +directory list, and shows different combinations of the two. One or more of the options below may be used to determine the files shown: diff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt index d1f9b5172d..3b432171d6 100644 --- a/Documentation/git-maintenance.txt +++ b/Documentation/git-maintenance.txt @@ -38,7 +38,7 @@ register:: for running in the background without disrupting foreground processes. + -The `register` subcomand will also set the `maintenance.strategy` config +The `register` subcommand will also set the `maintenance.strategy` config value to `incremental`, if this value is not previously set. The `incremental` strategy uses the following schedule for each maintenance task: @@ -218,6 +218,122 @@ Further, the `git gc` command should not be combined with but does not take the lock in the same way as `git maintenance run`. If possible, use `git maintenance run --task=gc` instead of `git gc`. +The following sections describe the mechanisms put in place to run +background maintenance by `git maintenance start` and how to customize +them. + +BACKGROUND MAINTENANCE ON POSIX SYSTEMS +--------------------------------------- + +The standard mechanism for scheduling background tasks on POSIX systems +is cron(8). This tool executes commands based on a given schedule. The +current list of user-scheduled tasks can be found by running `crontab -l`. +The schedule written by `git maintenance start` is similar to this: + +----------------------------------------------------------------------- +# BEGIN GIT MAINTENANCE SCHEDULE +# The following schedule was created by Git +# Any edits made in this region might be +# replaced in the future by a Git command. + +0 1-23 * * * "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=hourly +0 0 * * 1-6 "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=daily +0 0 * * 0 "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=weekly + +# END GIT MAINTENANCE SCHEDULE +----------------------------------------------------------------------- + +The comments are used as a region to mark the schedule as written by Git. +Any modifications within this region will be completely deleted by +`git maintenance stop` or overwritten by `git maintenance start`. + +The `crontab` entry specifies the full path of the `git` executable to +ensure that the executed `git` command is the same one with which +`git maintenance start` was issued independent of `PATH`. If the same user +runs `git maintenance start` with multiple Git executables, then only the +latest executable is used. + +These commands use `git for-each-repo --config=maintenance.repo` to run +`git maintenance run --schedule=<frequency>` on each repository listed in +the multi-valued `maintenance.repo` config option. These are typically +loaded from the user-specific global config. The `git maintenance` process +then determines which maintenance tasks are configured to run on each +repository with each `<frequency>` using the `maintenance.<task>.schedule` +config options. These values are loaded from the global or repository +config values. + +If the config values are insufficient to achieve your desired background +maintenance schedule, then you can create your own schedule. If you run +`crontab -e`, then an editor will load with your user-specific `cron` +schedule. In that editor, you can add your own schedule lines. You could +start by adapting the default schedule listed earlier, or you could read +the crontab(5) documentation for advanced scheduling techniques. Please +do use the full path and `--exec-path` techniques from the default +schedule to ensure you are executing the correct binaries in your +schedule. + + +BACKGROUND MAINTENANCE ON MACOS SYSTEMS +--------------------------------------- + +While macOS technically supports `cron`, using `crontab -e` requires +elevated privileges and the executed process does not have a full user +context. Without a full user context, Git and its credential helpers +cannot access stored credentials, so some maintenance tasks are not +functional. + +Instead, `git maintenance start` interacts with the `launchctl` tool, +which is the recommended way to schedule timed jobs in macOS. Scheduling +maintenance through `git maintenance (start|stop)` requires some +`launchctl` features available only in macOS 10.11 or later. + +Your user-specific scheduled tasks are stored as XML-formatted `.plist` +files in `~/Library/LaunchAgents/`. You can see the currently-registered +tasks using the following command: + +----------------------------------------------------------------------- +$ ls ~/Library/LaunchAgents/org.git-scm.git* +org.git-scm.git.daily.plist +org.git-scm.git.hourly.plist +org.git-scm.git.weekly.plist +----------------------------------------------------------------------- + +One task is registered for each `--schedule=<frequency>` option. To +inspect how the XML format describes each schedule, open one of these +`.plist` files in an editor and inspect the `<array>` element following +the `<key>StartCalendarInterval</key>` element. + +`git maintenance start` will overwrite these files and register the +tasks again with `launchctl`, so any customizations should be done by +creating your own `.plist` files with distinct names. Similarly, the +`git maintenance stop` command will unregister the tasks with `launchctl` +and delete the `.plist` files. + +To create more advanced customizations to your background tasks, see +launchctl.plist(5) for more information. + + +BACKGROUND MAINTENANCE ON WINDOWS SYSTEMS +----------------------------------------- + +Windows does not support `cron` and instead has its own system for +scheduling background tasks. The `git maintenance start` command uses +the `schtasks` command to submit tasks to this system. You can inspect +all background tasks using the Task Scheduler application. The tasks +added by Git have names of the form `Git Maintenance (<frequency>)`. +The Task Scheduler GUI has ways to inspect these tasks, but you can also +export the tasks to XML files and view the details there. + +Note that since Git is a console application, these background tasks +create a console window visible to the current user. This can be changed +manually by selecting the "Run whether user is logged in or not" option +in Task Scheduler. This change requires a password input, which is why +`git maintenance start` does not select it by default. + +If you want to customize the background tasks, please rename the tasks +so future calls to `git maintenance (start|stop)` do not overwrite your +custom tasks. + GIT --- diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt index fa6a756123..17a2603a60 100644 --- a/Documentation/git-mktag.txt +++ b/Documentation/git-mktag.txt @@ -3,7 +3,7 @@ git-mktag(1) NAME ---- -git-mktag - Creates a tag object +git-mktag - Creates a tag object with extra validation SYNOPSIS @@ -11,25 +11,52 @@ SYNOPSIS [verse] 'git mktag' +OPTIONS +------- + +--strict:: + By default mktag turns on the equivalent of + linkgit:git-fsck[1] `--strict` mode. Use `--no-strict` to + disable it. + DESCRIPTION ----------- -Reads a tag contents on standard input and creates a tag object -that can also be used to sign other objects. -The output is the new tag's <object> identifier. +Reads a tag contents on standard input and creates a tag object. The +output is the new tag's <object> identifier. + +This command is mostly equivalent to linkgit:git-hash-object[1] +invoked with `-t tag -w --stdin`. I.e. both of these will create and +write a tag found in `my-tag`: + + git mktag <my-tag + git hash-object -t tag -w --stdin <my-tag + +The difference is that mktag will die before writing the tag if the +tag doesn't pass a linkgit:git-fsck[1] check. + +The "fsck" check done mktag is stricter than what linkgit:git-fsck[1] +would run by default in that all `fsck.<msg-id>` messages are promoted +from warnings to errors (so e.g. a missing "tagger" line is an error). + +Extra headers in the object are also an error under mktag, but ignored +by linkgit:git-fsck[1]. This extra check can be turned off by setting +the appropriate `fsck.<msg-id>` varible: + + git -c fsck.extraHeaderEntry=ignore mktag <my-tag-with-headers Tag Format ---------- A tag signature file, to be fed to this command's standard input, has a very simple fixed format: four lines of - object <sha1> + object <hash> type <typename> tag <tagname> tagger <tagger> followed by some 'optional' free-form message (some tags created -by older Git may not have `tagger` line). The message, when +by older Git may not have `tagger` line). The message, when it exists, is separated by a blank line from the header. The message part may contain a signature that Git itself doesn't care about, but that can be verified with gpg. diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index ec233ac0c1..f89e68b424 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -397,7 +397,7 @@ changelist text. Exiting with a non-zero status from the script will abort the process. The purpose of the hook is to edit the message file in place, -and it is not supressed by the `--no-verify` option. This hook +and it is not suppressed by the `--no-verify` option. This hook is called even if `--prepare-p4-only` is set. p4-changelist diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 5013daa6ef..6b8ca085aa 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -212,6 +212,18 @@ Options for Files Only the names of the variables are listed, not their value, even if they are set. +--path-format=(absolute|relative):: + Controls the behavior of certain other options. If specified as absolute, the + paths printed by those options will be absolute and canonical. If specified as + relative, the paths will be relative to the current working directory if that + is possible. The default is option specific. ++ +This option may be specified multiple times and affects only the arguments that +follow it on the command line, either to the end of the command line or the next +instance of this option. + +The following options are modified by `--path-format`: + --git-dir:: Show `$GIT_DIR` if defined. Otherwise show the path to the .git directory. The path shown, when relative, is @@ -221,27 +233,9 @@ If `$GIT_DIR` is not defined and the current directory is not detected to lie in a Git repository or work tree print a message to stderr and exit with nonzero status. ---absolute-git-dir:: - Like `--git-dir`, but its output is always the canonicalized - absolute path. - --git-common-dir:: Show `$GIT_COMMON_DIR` if defined, else `$GIT_DIR`. ---is-inside-git-dir:: - When the current working directory is below the repository - directory print "true", otherwise "false". - ---is-inside-work-tree:: - When the current working directory is inside the work tree of the - repository print "true", otherwise "false". - ---is-bare-repository:: - When the repository is bare print "true", otherwise "false". - ---is-shallow-repository:: - When the repository is shallow print "true", otherwise "false". - --resolve-git-dir <path>:: Check if <path> is a valid repository or a gitfile that points at a valid repository, and print the location of the @@ -255,19 +249,9 @@ print a message to stderr and exit with nonzero status. $GIT_OBJECT_DIRECTORY is set to /foo/bar then "git rev-parse --git-path objects/abc" returns /foo/bar/abc. ---show-cdup:: - When the command is invoked from a subdirectory, show the - path of the top-level directory relative to the current - directory (typically a sequence of "../", or an empty string). - ---show-prefix:: - When the command is invoked from a subdirectory, show the - path of the current directory relative to the top-level - directory. - --show-toplevel:: - Show the absolute path of the top-level directory of the working - tree. If there is no working tree, report an error. + Show the (by default, absolute) path of the top-level directory + of the working tree. If there is no working tree, report an error. --show-superproject-working-tree:: Show the absolute path of the root of the superproject's @@ -279,6 +263,36 @@ print a message to stderr and exit with nonzero status. Show the path to the shared index file in split index mode, or empty if not in split-index mode. +The following options are unaffected by `--path-format`: + +--absolute-git-dir:: + Like `--git-dir`, but its output is always the canonicalized + absolute path. + +--is-inside-git-dir:: + When the current working directory is below the repository + directory print "true", otherwise "false". + +--is-inside-work-tree:: + When the current working directory is inside the work tree of the + repository print "true", otherwise "false". + +--is-bare-repository:: + When the repository is bare print "true", otherwise "false". + +--is-shallow-repository:: + When the repository is shallow print "true", otherwise "false". + +--show-cdup:: + When the command is invoked from a subdirectory, show the + path of the top-level directory relative to the current + directory (typically a sequence of "../", or an empty string). + +--show-prefix:: + When the command is invoked from a subdirectory, show the + path of the current directory relative to the top-level + directory. + --show-object-format[=(storage|input|output)]:: Show the object format (hash algorithm) used for the repository for storage inside the `.git` directory, input, or output. For diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index b7bbbeadef..93708aefea 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -494,10 +494,14 @@ edit ~/.gitconfig to specify your account settings: smtpServerPort = 587 ---- -If you have multifactor authentication setup on your gmail account, you will +If you have multi-factor authentication set up on your Gmail account, you will need to generate an app-specific password for use with 'git send-email'. Visit https://security.google.com/settings/security/apppasswords to create it. +If you do not have multi-factor authentication set up on your Gmail account, +you will need to allow less secure app access. Visit +https://myaccount.google.com/lesssecureapps to enable it. + Once your commits are ready to be sent to the mailing list, run the following commands: diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 7731b45f07..c0764e850a 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -184,11 +184,26 @@ characters, that field will be quoted in the manner of a C string literal: surrounded by ASCII double quote (34) characters, and with interior special characters backslash-escaped. -For paths with merge conflicts, `X` and `Y` show the modification -states of each side of the merge. For paths that do not have merge -conflicts, `X` shows the status of the index, and `Y` shows the status -of the work tree. For untracked paths, `XY` are `??`. Other status -codes can be interpreted as follows: +There are three different types of states that are shown using this format, and +each one uses the `XY` syntax differently: + +* When a merge is occurring and the merge was successful, or outside of a merge + situation, `X` shows the status of the index and `Y` shows the status of the + working tree. +* When a merge conflict has occurred and has not yet been resolved, `X` and `Y` + show the state introduced by each head of the merge, relative to the common + ancestor. These paths are said to be _unmerged_. +* When a path is untracked, `X` and `Y` are always the same, since they are + unknown to the index. `??` is used for untracked paths. Ignored files are + not listed unless `--ignored` is used; if it is, ignored files are indicated + by `!!`. + +Note that the term _merge_ here also includes rebases using the default +`--merge` strategy, cherry-picks, and anything else using the merge machinery. + +In the following table, these three classes are shown in separate sections, and +these characters are used for `X` and `Y` fields for the first two sections that +show tracked paths: * ' ' = unmodified * 'M' = modified @@ -198,9 +213,6 @@ codes can be interpreted as follows: * 'C' = copied * 'U' = updated but unmerged -Ignored files are not listed, unless `--ignored` option is in effect, -in which case `XY` are `!!`. - .... X Y Meaning ------------------------------------------------- diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index 1489cb09a0..2853f168d9 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -30,9 +30,8 @@ SYNOPSIS DESCRIPTION ----------- -Modifies the index or directory cache. Each file mentioned is updated -into the index and any 'unmerged' or 'needs updating' state is -cleared. +Modifies the index. Each file mentioned is updated into the index and +any 'unmerged' or 'needs updating' state is cleared. See also linkgit:git-add[1] for a more user-friendly way to do some of the most common operations on the index. diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index ffccfc7760..1f3b57d04d 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -644,7 +644,7 @@ changelist text. Exiting with a non-zero status from the script will abort the process. The purpose of the hook is to edit the message file in place, -and it is not supressed by the `--no-verify` option. This hook +and it is not suppressed by the `--no-verify` option. This hook is called even if `--prepare-p4-only` is set. Run `git-p4 submit --help` for details. diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt index 539b4e1997..8e333dde1b 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -7,7 +7,7 @@ gitmodules - Defining submodule properties SYNOPSIS -------- -$GIT_WORK_DIR/.gitmodules +$GIT_WORK_TREE/.gitmodules DESCRIPTION @@ -27,19 +27,19 @@ submodule.<name>.path:: Defines the path, relative to the top-level directory of the Git working tree, where the submodule is expected to be checked out. The path name must not end with a `/`. All submodule paths must - be unique within the .gitmodules file. + be unique within the `.gitmodules` file. submodule.<name>.url:: Defines a URL from which the submodule repository can be cloned. This may be either an absolute URL ready to be passed to - linkgit:git-clone[1] or (if it begins with ./ or ../) a location + linkgit:git-clone[1] or (if it begins with `./` or `../`) a location relative to the superproject's origin repository. In addition, there are a number of optional keys: submodule.<name>.update:: Defines the default update procedure for the named submodule, - i.e. how the submodule is updated by "git submodule update" + i.e. how the submodule is updated by the `git submodule update` command in the superproject. This is only used by `git submodule init` to initialize the configuration variable of the same name. Allowed values here are 'checkout', 'rebase', @@ -49,7 +49,7 @@ submodule.<name>.update:: submodule.<name>.branch:: A remote branch name for tracking updates in the upstream submodule. - If the option is not specified, it defaults to the remote 'HEAD'. + If the option is not specified, it defaults to the remote `HEAD`. A special value of `.` is used to indicate that the name of the branch in the submodule should be the same name as the current branch in the current repository. See the `--remote` documentation in @@ -57,14 +57,14 @@ submodule.<name>.branch:: submodule.<name>.fetchRecurseSubmodules:: This option can be used to control recursive fetching of this - submodule. If this option is also present in the submodules entry in - .git/config of the superproject, the setting there will override the - one found in .gitmodules. + submodule. If this option is also present in the submodule's entry in + `.git/config` of the superproject, the setting there will override the + one found in `.gitmodules`. Both settings can be overridden on the command line by using the - "--[no-]recurse-submodules" option to "git fetch" and "git pull". + `--[no-]recurse-submodules` option to `git fetch` and `git pull`. submodule.<name>.ignore:: - Defines under what circumstances "git status" and the diff family show + Defines under what circumstances `git status` and the diff family show a submodule as modified. The following values are supported: + -- @@ -73,7 +73,7 @@ submodule.<name>.ignore:: been staged). dirty;; All changes to the submodule's work tree will be ignored, only - committed differences between the HEAD of the submodule and its + committed differences between the `HEAD` of the submodule and its recorded state in the superproject are taken into account. untracked;; Only untracked files in submodules will be ignored. @@ -84,12 +84,12 @@ submodule.<name>.ignore:: differences, and modifications to tracked and untracked files are shown. This is the default option. -If this option is also present in the submodules entry in .git/config +If this option is also present in the submodule's entry in `.git/config` of the superproject, the setting there will override the one found in -.gitmodules. +`.gitmodules`. Both settings can be overridden on the command line by using the -"--ignore-submodules" option. The 'git submodule' commands are not +`--ignore-submodules` option. The `git submodule` commands are not affected by this setting. -- @@ -102,7 +102,7 @@ submodule.<name>.shallow:: EXAMPLES -------- -Consider the following .gitmodules file: +Consider the following `.gitmodules` file: ---- [submodule "libfoo"] diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt index f96b2e605f..96d2fc589f 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/technical/pack-format.txt @@ -55,6 +55,18 @@ Valid object types are: Type 5 is reserved for future expansion. Type 0 is invalid. +=== Size encoding + +This document uses the following "size encoding" of non-negative +integers: From each byte, the seven least significant bits are +used to form the resulting integer. As long as the most significant +bit is 1, this process continues; the byte with MSB 0 provides the +last seven bits. The seven-bit chunks are concatenated. Later +values are more significant. + +This size encoding should not be confused with the "offset encoding", +which is also used in this document. + === Deltified representation Conceptually there are only four object types: commit, tree, tag and @@ -73,7 +85,10 @@ Ref-delta can also refer to an object outside the pack (i.e. the so-called "thin pack"). When stored on disk however, the pack should be self contained to avoid cyclic dependency. -The delta data is a sequence of instructions to reconstruct an object +The delta data starts with the size of the base object and the +size of the object to be reconstructed. These sizes are +encoded using the size encoding from above. The remainder of +the delta data is a sequence of instructions to reconstruct the object from the base object. If the base object is deltified, it must be converted to canonical form first. Each instruction appends more and more data to the target object until it's complete. There are two diff --git a/Documentation/technical/reftable.txt b/Documentation/technical/reftable.txt index 2951840e9c..8095ab2590 100644 --- a/Documentation/technical/reftable.txt +++ b/Documentation/technical/reftable.txt @@ -446,7 +446,7 @@ especially if readers will not use the object name to ref mapping. Object blocks use unique, abbreviated 2-32 object name keys, mapping to ref blocks containing references pointing to that object directly, or as the peeled value of an annotated tag. Like ref blocks, object blocks use -the file's standard block size. The abbrevation length is available in +the file's standard block size. The abbreviation length is available in the footer as `obj_id_len`. To save space in small files, object blocks may be omitted if the ref |