diff options
Diffstat (limited to 'Documentation')
66 files changed, 790 insertions, 297 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 711cb9171e..0e27b5395d 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -499,6 +499,33 @@ For Python scripts: - Where required libraries do not restrict us to Python 2, we try to also be compatible with Python 3.1 and later. + +Program Output + + We make a distinction between a Git command's primary output and + output which is merely chatty feedback (for instance, status + messages, running transcript, or progress display), as well as error + messages. Roughly speaking, a Git command's primary output is that + which one might want to capture to a file or send down a pipe; its + chatty output should not interfere with these use-cases. + + As such, primary output should be sent to the standard output stream + (stdout), and chatty output should be sent to the standard error + stream (stderr). Examples of commands which produce primary output + include `git log`, `git show`, and `git branch --list` which generate + output on the stdout stream. + + Not all Git commands have primary output; this is often true of + commands whose main function is to perform an action. Some action + commands are silent, whereas others are chatty. An example of a + chatty action commands is `git clone` with its "Cloning into + '<path>'..." and "Checking connectivity..." status messages which it + sends to the stderr stream. + + Error messages from Git commands should always be sent to the stderr + stream. + + Error Messages - Do not end error messages with a full stop. diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index b20bc8e914..63a2ef5449 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -905,19 +905,34 @@ Sending emails with Git is a two-part process; before you can prepare the emails themselves, you'll need to prepare the patches. Luckily, this is pretty simple: ---- -$ git format-patch --cover-letter -o psuh/ master..psuh ----- - -The `--cover-letter` parameter tells `format-patch` to create a cover letter -template for you. You will need to fill in the template before you're ready -to send - but for now, the template will be next to your other patches. - -The `-o psuh/` parameter tells `format-patch` to place the patch files into a -directory. This is useful because `git send-email` can take a directory and -send out all the patches from there. - -`master..psuh` tells `format-patch` to generate patches for the difference -between `master` and `psuh`. It will make one patch file per commit. After you +$ git format-patch --cover-letter -o psuh/ --base=auto psuh@{u}..psuh +---- + + . The `--cover-letter` option tells `format-patch` to create a + cover letter template for you. You will need to fill in the + template before you're ready to send - but for now, the template + will be next to your other patches. + + . The `-o psuh/` option tells `format-patch` to place the patch + files into a directory. This is useful because `git send-email` + can take a directory and send out all the patches from there. + + . The `--base=auto` option tells the command to record the "base + commit", on which the recipient is expected to apply the patch + series. The `auto` value will cause `format-patch` to compute + the base commit automatically, which is the merge base of tip + commit of the remote-tracking branch and the specified revision + range. + + . The `psuh@{u}..psuh` option tells `format-patch` to generate + patches for the commits you created on the `psuh` branch since it + forked from its upstream (which is `origin/master` if you + followed the example in the "Set up your workspace" section). If + you are already on the `psuh` branch, you can just say `@{u}`, + which means "commits on the current branch since it forked from + its upstream", which is the same thing. + +The command will make one patch file per commit. After you run, you can go have a look at each of the patches with your favorite text editor and make sure everything looks alright; however, it's not recommended to make code fixups via the patch file. It's a better idea to make the change the diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt index 45eb84d8b4..ca267941f3 100644 --- a/Documentation/MyFirstObjectWalk.txt +++ b/Documentation/MyFirstObjectWalk.txt @@ -58,14 +58,19 @@ running, enable trace output by setting the environment variable `GIT_TRACE`. Add usage text and `-h` handling, like all subcommands should consistently do (our test suite will notice and complain if you fail to do so). +We'll need to include the `parse-options.h` header. ---- +#include "parse-options.h" + +... + int cmd_walken(int argc, const char **argv, const char *prefix) { const char * const walken_usage[] = { N_("git walken"), NULL, - } + }; struct option options[] = { OPT_END() }; @@ -195,9 +200,14 @@ Similarly to the default values, we don't have anything to do here yet ourselves; however, we should call `git_default_config()` if we aren't calling any other existing config callbacks. -Add a new function to `builtin/walken.c`: +Add a new function to `builtin/walken.c`. +We'll also need to include the `config.h` header: ---- +#include "config.h" + +... + static int git_walken_config(const char *var, const char *value, void *cb) { /* @@ -229,8 +239,14 @@ typically done by calling `repo_init_revisions()` with the repository you intend to target, as well as the `prefix` argument of `cmd_walken` and your `rev_info` struct. -Add the `struct rev_info` and the `repo_init_revisions()` call: +Add the `struct rev_info` and the `repo_init_revisions()` call. +We'll also need to include the `revision.h` header: + ---- +#include "revision.h" + +... + int cmd_walken(int argc, const char **argv, const char *prefix) { /* This can go wherever you like in your declarations.*/ @@ -624,9 +640,14 @@ static void walken_object_walk(struct rev_info *rev) ---- Let's start by calling just the unfiltered walk and reporting our counts. -Complete your implementation of `walken_object_walk()`: +Complete your implementation of `walken_object_walk()`. +We'll also need to include the `list-objects.h` header. ---- +#include "list-objects.h" + +... + traverse_commit_list(rev, walken_show_commit, walken_show_object, NULL); printf("commits %d\nblobs %d\ntags %d\ntrees %d\n", commit_count, @@ -697,7 +718,7 @@ First, we'll need to `#include "list-objects-filter-options.h"` and set up the ---- static void walken_object_walk(struct rev_info *rev) { - struct list_objects_filter_options filter_options = {}; + struct list_objects_filter_options filter_options = { 0 }; ... ---- diff --git a/Documentation/RelNotes/2.35.0.txt b/Documentation/RelNotes/2.35.0.txt new file mode 100644 index 0000000000..aa311cb96e --- /dev/null +++ b/Documentation/RelNotes/2.35.0.txt @@ -0,0 +1,285 @@ +Git 2.35 Release Notes +====================== + +Updates since Git 2.34 +---------------------- + +Backward compatibility warts + + * "_" is now treated as any other URL-valid characters in an URL when + matching the per-URL configuration variable names. + + +UI, Workflows & Features + + * "git status --porcelain=v2" now show the number of stash entries + with --show-stash like the normal output does. + + * "git stash" learned the "--staged" option to stash away what has + been added to the index (and nothing else). + + * "git var GIT_DEFAULT_BRANCH" is a way to see what name is used for + the newly created branch if "git init" is run. + + * Various operating modes of "git reset" have been made to work + better with the sparse index. + + * "git submodule deinit" for a submodule whose .git metadata + directory is embedded in its working tree refused to work, until + the submodule gets converted to use the "absorbed" form where the + metadata directory is stored in superproject, and a gitfile at the + top-level of the working tree of the submodule points at it. The + command is taught to convert such submodules to the absorbed form + as needed. + + * The completion script (in contrib/) learns that the "--date" + option of commands from the "git log" family takes "human" and + "auto" as valid values. + + * "Zealous diff3" style of merge conflict presentation has been added. + + * The "git log --format=%(describe)" placeholder has been extended to + allow passing selected command-line options to the underlying "git + describe" command. + + * "default" and "reset" have been added to our color palette. + + * The cryptographic signing using ssh keys can specify literal keys + for keytypes whose name do not begin with the "ssh-" prefix by + using the "key::" prefix mechanism (e.g. "key::ecdsa-sha2-nistp256"). + + * "git fetch" without the "--update-head-ok" option ought to protect + a checked out branch from getting updated, to prevent the working + tree that checks it out to go out of sync. The code was written + before the use of "git worktree" got widespread, and only checked + the branch that was checked out in the current worktree, which has + been updated. + + * "git name-rev" has been tweaked to give output that is shorter and + easier to understand. + + * "git apply" has been taught to ignore a message without a patch + with the "--allow-empty" option. It also learned to honor the + "--quiet" option given from the command line. + + * The "init" and "set" subcommands in "git sparse-checkout" have been + unified for a better user experience and performance. + + +Performance, Internal Implementation, Development Support etc. + + * The use of errno as a means to carry the nature of error in the ref + API implementation has been reworked and reduced. + + * Teach and encourage first-time contributors to this project to + state the base commit when they submit their topic. + + * The command line complation for "git send-email" options have been + tweaked to make it easier to keep it in sync with the command itself. + + * Ensure that the sparseness of the in-core index matches the + index.sparse configuration specified by the repository immediately + after the on-disk index file is read. + + * Code clean-up to eventually allow information on remotes defined + for an arbitrary repository to be read. + + * Build optimization. + + * Tighten code for testing pack-bitmap. + + * Weather balloon to break people with compilers that do not support + C99. + + * The "reftable" backend for the refs API, without integrating into + the refs subsystem, has been added. + + * More tests are marked as leak-free. + + * The test framework learns to list unsatisfied test prerequisites, + and optionally error out when prerequisites that are expected to be + satisfied are not. + + * The default setting for trace2 event nesting was too low to cause + test failures, which is worked around by bumping it up in the test + framework. + + * Drop support for TravisCI and update test workflows at GitHub. + + * Many tests that used to need GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME + mechanism to force "git" to use 'master' as the default name for + the initial branch no longer need it; the use of the mechanism from + them have been removed. + + * Allow running our tests while disabling fsync. + + * Document the parameters given to the reflog entry iterator callback + functions. + (merge e6e94f34b2 jc/reflog-iterator-callback-doc later to maint). + + * The test helper for refs subsystem learned to write bogus and/or + nonexistent object name to refs to simulate error situations we + want to test Git in. + + * "diff --histogram" optimization. + + * Weather balloon to find compilers that do not grok variable + declaration in the for() loop. + + * diff and blame commands have been taught to work better with sparse + index. + + * The chainlint test script linter in the test suite has been updated. + + * The DEVELOPER=yes build uses -std=gnu99 now. + + * "git format-patch" uses a single rev_info instance and then exits. + Mark the structure with UNLEAK() macro to squelch leak sanitizer. + + * New interface into the tmp-objdir API to help in-core use of the + quarantine feature. + + * Broken &&-chains in the test scripts have been corrected. + + +Fixes since v2.34 +----------------- + + * "git grep" looking in a blob that has non-UTF8 payload was + completely broken when linked with certain versions of PCREv2 + library in the latest release. + + * Other code cleanup, docfix, build fix, etc. + + * "git pull" with any strategy when the other side is behind us + should succeed as it is a no-op, but doesn't. + + * An earlier change in 2.34.0 caused JGit application (that abused + GIT_EDITOR mechanism when invoking "git config") to get stuck with + a SIGTTOU signal; it has been reverted. + + * An earlier change that broke .gitignore matching has been reverted. + + * Things like "git -c branch.sort=bogus branch new HEAD", i.e. the + operation modes of the "git branch" command that do not need the + sort key information, no longer errors out by seeing a bogus sort + key. + (merge 98e7ab6d42 jc/fix-ref-sorting-parse later to maint). + + * The compatibility implementation for unsetenv(3) were written to + mimic ancient, non-POSIX, variant seen in an old glibc; it has been + changed to return an integer to match the more modern era. + (merge a38989bd5b jc/unsetenv-returns-an-int later to maint). + + * The clean/smudge conversion code path has been prepared to better + work on platforms where ulong is narrower than size_t. + (merge 596b5e77c9 mc/clean-smudge-with-llp64 later to maint). + + * Redact the path part of packfile URI that appears in the trace output. + (merge 0ba558ffb1 if/redact-packfile-uri later to maint). + + * CI has been taught to catch some Unicode directional formatting + sequence that can be used in certain mischief. + (merge 0e7696c64d js/ci-no-directional-formatting later to maint). + + * The "--date=format:<strftime>" gained a workaround for the lack of + system support for a non-local timezone to handle "%s" placeholder. + (merge 9b591b9403 jk/strbuf-addftime-seconds-since-epoch later to maint). + + * The "merge" subcommand of "git jump" (in contrib/) silently ignored + pathspec and other parameters. + (merge 67ba13e5a4 jk/jump-merge-with-pathspec later to maint). + + * The code to decode the length of packed object size has been + corrected. + (merge 34de5b8eac jt/pack-header-lshift-overflow later to maint). + + * The advice message given by "git pull" when the user hasn't made a + choice between merge and rebase still said that the merge is the + default, which no longer is the case. This has been corrected. + (merge 71076d0edd ah/advice-pull-has-no-preference-between-rebase-and-merge later to maint). + + * "git fetch", when received a bad packfile, can fail with SIGPIPE. + This wasn't wrong per-se, but we now detect the situation and fail + in a more predictable way. + (merge 2a4aed42ec jk/fetch-pack-avoid-sigpipe-to-index-pack later to maint). + + * The function to cull a child process and determine the exit status + had two separate code paths for normal callers and callers in a + signal handler, and the latter did not yield correct value when the + child has caught a signal. The handling of the exit status has + been unified for these two code paths. An existing test with + flakiness has also been corrected. + (merge 5263e22cba jk/t7006-sigpipe-tests-fix later to maint). + + * When a non-existent program is given as the pager, we tried to + reuse an uninitialized child_process structure and crashed, which + has been fixed. + (merge f917f57f40 em/missing-pager later to maint). + + * The single-key-input mode in "git add -p" had some code to handle + keys that generate a sequence of input via ReadKey(), which did not + handle end-of-file correctly, which has been fixed. + (merge fc8a8126df cb/add-p-single-key-fix later to maint). + + * "git rebase -x" added an unnecessary 'exec' instructions before + 'noop', which has been corrected. + (merge cc9dcdee61 en/rebase-x-fix later to maint). + + * When the "git push" command is killed while the receiving end is + trying to report what happened to the ref update proposals, the + latter used to die, due to SIGPIPE. The code now ignores SIGPIPE + to increase our chances to run the post-receive hook after it + happens. + (merge d34182b9e3 rj/receive-pack-avoid-sigpipe-during-status-reporting later to maint). + + * "git worktree add" showed "Preparing worktree" message to the + standard output stream, but when it failed, the message from die() + went to the standard error stream. Depending on the order the + stdio streams are flushed at the program end, this resulted in + confusing output. It has been corrected by sending all the chatty + messages to the standard error stream. + (merge b50252484f es/worktree-chatty-to-stderr later to maint). + + * Coding guideline document has been updated to clarify what goes to + standard error in our system. + (merge e258eb4800 es/doc-stdout-vs-stderr later to maint). + + * The sparse-index/sparse-checkout feature had a bug in its use of + the matching code to determine which path is in or outside the + sparse checkout patterns. + (merge 8c5de0d265 ds/sparse-deep-pattern-checkout-fix later to maint). + + * "git rebase -x" by mistake started exporting the GIT_DIR and + GIT_WORK_TREE environment variables when the command was rewritten + in C, which has been corrected. + (merge 434e0636db en/rebase-x-wo-git-dir-env later to maint). + + * When "git log" implicitly enabled the "decoration" processing + without being explicitly asked with "--decorate" option, it failed + to read and honor the settings given by the "--decorate-refs" + option. + + * "git fetch --set-upstream" did not check if there is a current + branch, leading to a segfault when it is run on a detached HEAD, + which has been corrected. + (merge 17baeaf82d ab/fetch-set-upstream-while-detached later to maint). |