diff --git a/.clang-format b/.clang-format index de1c8b5c77f756..41d4cd23fd97f5 100644 --- a/.clang-format +++ b/.clang-format @@ -149,7 +149,7 @@ Cpp11BracedListStyle: false # A list of macros that should be interpreted as foreach loops instead of as # function calls. -ForEachMacros: ['for_each_string_list_item'] +ForEachMacros: ['for_each_string_list_item', 'for_each_wanted_builtin', 'for_each_builtin', 'for_each_ut'] # The maximum number of consecutive empty lines to keep. MaxEmptyLinesToKeep: 1 diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 64e605a02b71c5..e7b4e2f3c204c2 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -5,7 +5,7 @@ Git community does not use github.com for their contributions. Instead, we use a mailing list (git@vger.kernel.org) for code submissions, code reviews, and bug reports. -Nevertheless, you can use [submitGit](http://submitgit.herokuapp.com/) to +Nevertheless, you can use [GitGitGadget](https://gitgitgadget.github.io/) to conveniently send your Pull Requests commits to our mailing list. Please read ["A note from the maintainer"](https://git.kernel.org/pub/scm/git/git.git/plain/MaintNotes?h=todo) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 07b255f286e889..5d22900328aa3c 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,18 +1,19 @@ Thanks for taking the time to contribute to Git! Those seeking to contribute to the Git for Windows fork should see -http://gitforwindows.org/#contribute on how to contribute Windows specific enhancements. +http://gitforwindows.org/#contribute on how to contribute Windows specific +enhancements. If your contribution is for the core Git functions and documentation please be aware that the Git community does not use the github.com issues -or pull request mechanism for their contributions. +or pull request mechanism for their contributions. -Instead, we use the Git mailing list (git@vger.kernel.org) for code and +Instead, we use the Git mailing list (git@vger.kernel.org) for code and documenatation submissions, code reviews, and bug reports. The mailing list is plain text only (anything with HTML is sent directly -to the spam folder). +to the spam folder). -Nevertheless, you can use submitGit to conveniently send your Pull -Requests commits to our mailing list. +Nevertheless, you can use GitGitGadget (https://gitgitgadget.github.io/) +to conveniently send your Pull Requests commits to our mailing list. Please read the "guidelines for contributing" linked above! diff --git a/.gitignore b/.gitignore index 3f5cb250d7fc7c..fff8e538d5c39b 100644 --- a/.gitignore +++ b/.gitignore @@ -82,8 +82,6 @@ /git-init-db /git-interpret-trailers /git-instaweb -/git-legacy-rebase -/git-legacy-rebase--interactive /git-legacy-stash /git-log /git-ls-files @@ -137,7 +135,6 @@ /git-remote-ftps /git-remote-fd /git-remote-ext -/git-remote-testgit /git-remote-testpy /git-remote-testsvn /git-repack @@ -145,6 +142,7 @@ /git-request-pull /git-rerere /git-reset +/git-restore /git-rev-list /git-rev-parse /git-revert @@ -169,6 +167,7 @@ /git-submodule /git-submodule--helper /git-svn +/git-switch /git-symbolic-ref /git-tag /git-unpack-file diff --git a/.travis.yml b/.travis.yml index 36cbdea7f4f37e..ffb1bc46f2d960 100644 --- a/.travis.yml +++ b/.travis.yml @@ -21,16 +21,6 @@ matrix: compiler: addons: before_install: - - env: jobname=Windows - os: linux - compiler: - addons: - before_install: - script: - - > - test "$TRAVIS_REPO_SLUG" != "git/git" || - ci/run-windows-build.sh $TRAVIS_BRANCH $(git rev-parse HEAD) - after_failure: - env: jobname=Linux32 os: linux compiler: diff --git a/Documentation/.gitignore b/Documentation/.gitignore index 3ef54e0adbad5f..784e1464d3574e 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -12,4 +12,7 @@ cmds-*.txt mergetools-*.txt manpage-base-url.xsl SubmittingPatches.txt +MyFirstContribution.txt tmp-doc-diff/ +GIT-ASCIIDOCFLAGS +/GIT-EXCLUDED-PROGRAMS diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 8579530710a7e2..32210a4386c329 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -580,11 +580,14 @@ Writing Documentation: or commands: Literal examples (e.g. use of command-line options, command names, - branch names, configuration and environment variables) must be - typeset in monospace (i.e. wrapped with backticks): + branch names, URLs, pathnames (files and directories), configuration and + environment variables) must be typeset in monospace (i.e. wrapped with + backticks): `--pretty=oneline` `git rev-list` `remote.pushDefault` + `http://git.example.com` + `.git/config` `GIT_DIR` `HEAD` diff --git a/Documentation/Makefile b/Documentation/Makefile index fdd4a4b41016d8..b2769d6a667c1a 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -7,12 +7,14 @@ ARTICLES = SP_ARTICLES = OBSOLETE_HTML = +-include GIT-EXCLUDED-PROGRAMS + MAN1_TXT += $(filter-out \ + $(patsubst %,%.txt,$(EXCLUDED_PROGRAMS)) \ $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \ $(wildcard git-*.txt)) MAN1_TXT += git.txt MAN1_TXT += gitk.txt -MAN1_TXT += gitremote-helpers.txt MAN1_TXT += gitweb.txt MAN5_TXT += gitattributes.txt @@ -30,6 +32,7 @@ MAN7_TXT += gitdiffcore.txt MAN7_TXT += giteveryday.txt MAN7_TXT += gitglossary.txt MAN7_TXT += gitnamespaces.txt +MAN7_TXT += gitremote-helpers.txt MAN7_TXT += gitrevisions.txt MAN7_TXT += gitsubmodules.txt MAN7_TXT += gittutorial-2.txt @@ -74,6 +77,7 @@ API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technica SP_ARTICLES += $(API_DOCS) TECH_DOCS += SubmittingPatches +TECH_DOCS += MyFirstContribution TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol TECH_DOCS += technical/index-format @@ -331,6 +335,15 @@ mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*) show_tool_names can_merge "* " || :' >mergetools-merge.txt && \ date >$@ +TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK)) + +GIT-ASCIIDOCFLAGS: FORCE + @FLAGS='$(TRACK_ASCIIDOCFLAGS)'; \ + if test x"$$FLAGS" != x"`cat GIT-ASCIIDOCFLAGS 2>/dev/null`" ; then \ + echo >&2 " * new asciidoc flags"; \ + echo "$$FLAGS" >GIT-ASCIIDOCFLAGS; \ + fi + clean: $(RM) *.xml *.xml.new *.html *.html.new *.1 *.5 *.7 $(RM) *.texi *.texi.new *.texi.new.new git.info gitman.info @@ -338,15 +351,17 @@ clean: $(RM) howto-index.txt howto/*.html doc.dep $(RM) technical/*.html technical/api-index.txt $(RM) SubmittingPatches.txt + $(RM) MyFirstContribution.txt $(RM) $(cmds_txt) $(mergetools_txt) *.made $(RM) manpage-base-url.xsl + $(RM) GIT-ASCIIDOCFLAGS -$(MAN_HTML): %.html : %.txt asciidoc.conf +$(MAN_HTML): %.html : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS $(QUIET_ASCIIDOC)$(RM) $@.new $@ && \ $(TXT_TO_HTML) -d manpage -o $@.new $< && \ mv $@.new $@ -$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf +$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS $(QUIET_ASCIIDOC)$(RM) $@.new $@ && \ $(TXT_TO_HTML) -o $@.new $< && \ mv $@.new $@ @@ -354,16 +369,16 @@ $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf manpage-base-url.xsl: manpage-base-url.xsl.in $(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@ -%.1 %.5 %.7 : %.xml manpage-base-url.xsl +%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl) $(QUIET_XMLTO)$(RM) $@ && \ $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< -%.xml : %.txt asciidoc.conf +%.xml : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS $(QUIET_ASCIIDOC)$(RM) $@.new $@ && \ $(TXT_TO_XML) -d manpage -o $@.new $< && \ mv $@.new $@ -user-manual.xml: user-manual.txt user-manual.conf +user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS $(QUIET_ASCIIDOC)$(RM) $@.new $@ && \ $(TXT_TO_XML) -d book -o $@.new $< && \ mv $@.new $@ @@ -373,12 +388,16 @@ technical/api-index.txt: technical/api-index-skel.txt \ $(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ -$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt asciidoc.conf +$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt \ + asciidoc.conf GIT-ASCIIDOCFLAGS $(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt SubmittingPatches.txt: SubmittingPatches $(QUIET_GEN) cp $< $@ +MyFirstContribution.txt: MyFirstContribution + $(QUIET_GEN) cp $< $@ + XSLT = docbook.xsl XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css @@ -430,7 +449,7 @@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt WEBDOC_DEST = /pub/software/scm/git/docs howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ -$(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt +$(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt GIT-ASCIIDOCFLAGS $(QUIET_ASCIIDOC)$(RM) $@.new $@ && \ sed -e '1,/^$$/d' $< | \ $(TXT_TO_HTML) - >$@.new && \ diff --git a/Documentation/MyFirstContribution b/Documentation/MyFirstContribution new file mode 100644 index 00000000000000..28a94374c40140 --- /dev/null +++ b/Documentation/MyFirstContribution @@ -0,0 +1,887 @@ +My First Contribution to the Git Project +======================================== + +== Summary + +This is a tutorial demonstrating the end-to-end workflow of creating a change to +the Git tree, sending it for review, and making changes based on comments. + +=== Prerequisites + +This tutorial assumes you're already fairly familiar with using Git to manage +source code. The Git workflow steps will largely remain unexplained. + +=== Related Reading + +This tutorial aims to summarize the following documents, but the reader may find +useful additional context: + +- Documentation/SubmittingPatches +- Documentation/howto/new-command.txt + +== Getting Started + +=== Pull the Git codebase + +Git is mirrored in a number of locations. https://git-scm.com/downloads +suggests the best place to clone from is GitHub. + +---- +git clone https://github.com/git/git git +---- + +=== Identify Problem to Solve + +In this tutorial, we will add a new command, `git psuh`, short for "Pony Saying +`Um, Hello'" - a feature which has gone unimplemented despite a high frequency +of invocation during users' typical daily workflow. + +(We've seen some other effort in this space with the implementation of popular +commands such as `sl`.) + +=== Set Up Your Workspace + +Let's start by making a development branch to work on our changes. Per +`Documentation/SubmittingPatches`, since a brand new command is a new feature, +it's fine to base your work on `master`. However, in the future for bugfixes, +etc., you should check that doc and base it on the appropriate branch. + +For the purposes of this doc, we will base all our work on the `master` branch +of the upstream project. Create the `psuh` branch you will use for development +like so: + +---- +git checkout -b psuh origin/master +---- + +We'll make a number of commits here in order to demonstrate how to send many +patches up for review simultaneously. + +== Code It Up! + +NOTE: A reference implementation can be found at +https://github.com/nasamuffin/git/tree/psuh. + +=== Adding a new command + +Lots of the main useful commands are written as builtins, which means they are +implemented in C and compiled into the main `git` executable. Since they are so +common, it is a useful exercise to implement `git psuh` as a builtin subcommand. + +Built-in subcommands are typically implemented in a function named "cmd_" +followed by the name of the subcommand, in a source file named after the +subcommand and contained within `builtin/`. So it makes sense to implement your +command in `builtin/psuh.c`. Create that file, and within, write the entry point +for your command in a function matching the style and signature: + +---- +int cmd_psuh(int argc, const char **argv, const char *prefix) +---- + +We'll also need to add the extern declaration of psuh; open up `builtin.h`, +find the declaration for cmd_push, and add a new line for psuh: + +---- +extern int cmd_psuh(int argc, const char **argv, const char *prefix); +---- + +Be sure to `#include "builtin.h"` in your `psuh.c`. + +Go ahead and add some throwaway printf to that function. This is a decent +starting point as we can now add build rules and register the command. + +NOTE: Your throwaway text, as well as much of the text you will be adding over +the course of this lab, is user-facing. That means it needs to be localizable. +Take a look at `po/README` under "Marking strings for translation". Throughout +the lab, we will mark strings for translation as necessary; you should also do +so when writing your user-facing commands in the future. + +---- +int cmd_psuh(int argc, const char **argv, const char *prefix) +{ + printf(_("Pony saying hello goes here.\n")); + return 0; +} +---- + +Let's try to build it. Open Makefile, find where `builtin/push.o` is added +to BUILTIN_OBJS, and add `builtin/psuh.o` in the same way next to it in +alphabetical order.. Once you've done so, move to the top-level directory and +build simply with `make`. Also add the DEVELOPER=1 variable to turn on +some additional warnings: + +---- +echo DEVELOPER=1 >config.mak +make +---- + +NOTE: When you are developing the Git project, it's preferred that you use the +DEVELOPER flag; if there's some reason it doesn't work for you, you can turn it +off, but it's a good idea to mention the problem to the mailing list. + +NOTE: The Git build is parallelizable. `-j#` is not included above but you can +use it as you prefer, here and elsewhere. + +Great, now your new command builds happily on its own. But nobody invokes it. +Let's change that. + +The list of commands lives in `git.c`. We can register a new command by adding +a cmd_struct to the commands[] array. struct cmd_struct takes a string with the +command name, a function pointer to the command implementation, and a setup +option flag. For now, let's keep cheating off of push. Find the line where +cmd_push is registered, copy it, and modify it for cmd_psuh, placing the new +line in alphabetical order. + +The options are documented in `builtin.h` under "Adding a new built-in." Since +we hope to print some data about the user's current workspace context later, +we need a Git directory, so choose `RUN_SETUP` as your only option. + +Go ahead and build again. You should see a clean build, so let's kick the tires +and see if it works. There's a binary you can use to test with in +`./bin-wrappers`. + +---- +./bin-wrappers/git psuh +---- + +Check it out! You've got a command! Nice work! Let's commit this. + +---- +git add Makefile builtin.h builtin/psuh.c git.c +git commit -s +---- + +Consider something like the following as your commit message. Start the commit +with a 50-column or less subject line, including the name of the component +you're working on. Remember to be explicit and provide the "Why" of your commit, +especially if it couldn't easily be understood from your diff. When editing +your commit message, don't remove the Signed-off-by line which was added by `-s` +above. + +---- +psuh: add a new built-in by popular demand + +Internal metrics indicate this is a command many users expect to be +present. So here's an implementation to help drive customer +satisfaction and engagement: a pony which doubtfully greets the user, +or, a Pony Saying "Um, Hello" (PSUH). + +This commit message is intentionally formatted to 72 columns per line, +starts with a single line as "commit message subject" that is written as +if to command the codebase to do something (add this, teach a command +that). The body of the message is designed to add information about the +commit that is not readily deduced from reading the associated diff, +such as answering the question "why?". + +Signed-off-by: A U Thor +---- + +Go ahead and inspect your new commit with `git show`. "psuh:" indicates you +have modified mainly the `psuh` command. The subject line gives readers an idea +of what you've changed. The signed-off line (-s) indicates that you agree to +the Developer's Certificate of Origin 1.1 (see the SubmittingPatches [[dco]] +header). If you wish to add some context to your change, go ahead with +`git commit --amend`. + +For the remainder of the tutorial, the subject line only will be listed for the +sake of brevity. However, fully-fleshed example commit messages are available +on the reference implementation linked at the top of this document. + +=== Implementation + +It's probably useful to do at least something besides print out a string. Let's +start by having a look at everything we get. + +Modify your `cmd_psuh` implementation to dump the args you're passed: + +---- + printf(Q_("Your args (there is %i):\n", + "Your args (there are %i):\n", + argc), + argc); + for (int i = 0; i < argc; i++) { + printf("%s\n", argv[i]); + } + printf(_("Your prefix:\n%s\n"), prefix); +---- + +As you may expect, there's pretty much just whatever we give on the command +line, including the name of our command. (If `prefix` is empty for you, try +`cd Documentation/ && ../bin-wrappers/git/ psuh`). That's not so helpful. So +what other context can we get? + +Add a line to `#include "config.h"`. Then, add the following bits: + +---- +const char *cfg_name; + +... + +git_config(git_default_config, NULL) +if (git_config_get_string_const("user.name", &cfg_name) > 0) +{ + printf(_("No name is found in config\n")); +} +else +{ + printf(_("Your name: %s\n"), cfg_name); +} +---- + +git_config(...) will grab the configuration from config files known to Git and +apply standard precedence rules. git_config_get_string_const(...) will look up +a specific key ("user.name") and give you the value. There are a number of +single-key lookup functions like this one; you can see them all (and more info +about how to use git_config()) in `Documentation/technical/api-config.txt`. + +You should see that the name printed matches the one you see when you run: + +---- +git config --get user.name +---- + +Great! Now we know how to check for values in the git config. Let's commit this +too, so we don't lose our progress. + +---- +git add builtin/psuh.c +git commit -sm "psuh: show parameters & config opts" +---- + +Still, it'd be nice to know what the user's working context is like. Let's see +if we can print the name of the user's current branch. We can cheat off of the +`git status` implementation; the printer is located in `wt-status.c` and we can +see that the branch is held in a `struct wt_status`. `wt_status_print()` gets +invoked by `cmd_status()` in `builtin/commit.c`. Looking at that implementation +we see the status config being populated like so: + +---- +status_init_config(&s, git_status_config); +---- + +But as we drill down, we can find that `status_init_config()` wraps a call +to `git_config()`. Let's modify the code we wrote in the previous commit. + +---- +#include "wt-status.h" + +... + +// Add a wt_status to fill at the top. +struct wt_status status; + +... + +// modify the prior code: +wt_status_prepare(the_repository, &status); +git_config(git_default_config, &status); + +... + +printf(_("Your current branch: %s\n"), status.branch); +---- + +Run it again. Check it out - here's the (verbose) name of your current branch! + +Let's commit this as well. + +---- +git commit -sm "psuh: print the current branch" +---- + +Now let's see if we can get some info about a specific commit. + +Luckily, there are some helpers for us here. `commit.h` has a function called +`lookup_commit_reference_by_name` to which we can simply provide a hardcoded +string; `pretty.h` has an extremely handy `pp_commit_easy()` call which doesn't +require a full format object to be passed. + +Add the following: + +---- +#include "commit.h" +#include "pretty.h" + +... + +struct commit *c = NULL; +struct strbuf commitline; +strbuf_init(&commitline, 0); + +... + +c = lookup_commit_reference_by_name("origin/master"); + +if (c != NULL) +{ + pp_commit_easy(CMIT_FMT_ONELINE, c, &commitline); + printf(_("Current commit: %s\n"), commitline.buf); +} +---- + +The `struct strbuf` provides some safety belts to your basic `char*`, one of +which is a length member to prevent buffer overruns. It needs to be initialized +nicely with `strbuf_init`. Keep it in mind when you need to pass around `char*`. + +`lookup_commit_reference_by_name` resolves the name you pass it, so you can play +with the value there and see what kind of things you can come up with. + +`pp_commit_easy` is a convenience wrapper in `pretty.h` that takes a single +format enum shorthand, rather than an entire format struct. It then prints the +commit according to that shorthand. These are similar to the formats available +with `--pretty=FOO` in many Git commands. + +Build it and run, and if you're using the same name in the example, you should +see the subject line of the most recent commit in `origin/master` that you know +about. Neat! Let's commit that as well. + +---- +git commit -sm "psuh: display the top of origin/master" +---- + +=== Adding documentation + +Awesome! You've got a fantastic new command that you're ready to share with the +community. But hang on just a minute - this isn't very user-friendly. Run the +following: + +---- +./bin-wrappers/git help psuh +---- + +Your new command is undocumented! Let's fix that. + +Take a look at `Documentation/git-*.txt`. These are the manpages for the +subcommands that Git knows about. You can open these up and take a look to get +acquainted with the format, but then go ahead and make a new file +`Documentation/git-psuh.txt`. Like with most of the documentation in the Git +project, help pages are written with AsciiDoc (see CodingGuidelines, "Writing +Documentation" section). Use the following template to fill out your own +manpage: + +// Surprisingly difficult to embed AsciiDoc source within AsciiDoc. +[listing] +.... +git-psuh(1) +=========== + +NAME +---- +git-psuh - Delight users' typo with a shy horse + + +SYNOPSIS +-------- +[verse] +'git-psuh' + +DESCRIPTION +----------- +... + +OPTIONS[[OPTIONS]] +------------------ +... + +OUTPUT +------ +... + + +GIT +--- +Part of the linkgit:git[1] suite +.... + +The most important pieces of this to note are the file header, underlined by =, +the NAME section, and the SYNOPSIS, which would normally contain the grammar if +your command took arguments. Feel free to add new headers if you wish. + +Now that you've written your manpage, you'll need to build it explicitly. We +convert your AsciiDoc to troff which is man-readable like so: + +---- +make all doc +man Documentation/git-psuh.1 +---- + +or + +---- +make -C Documentation/git-psuh.1 +man Documentation/git-psuh.1 +---- + +NOTE: You may need to install the package `asciidoc` to get this to work. + +While this isn't as satisfying as running through `git help`, you can at least +check that your help page looks right. + +You can also check that the documentation coverage is good (that is, the project +sees that your command has been implemented as well as documented) by running +`make check-docs` from the top-level. + +Go ahead and commit your new documentation change. + +=== Adding usage text + +Try and run `./bin-wrappers/git psuh -h`. Your command should crash at the end. +That's because `-h` is a special case which your command should handle by +printing usage. + +Take a look at `Documentation/technical/api-parse-options.txt`. This is a handy +tool for pulling out options you need to be able to handle, and it takes a +usage string. + +In order to use it, we'll need to prepare a NULL-terminated usage string and a +builtin_psuh_options array. Add a line to `#include "parse-options.h"`. + +At global scope, add your usage: + +---- +static const char * const psuh_usage[] = { + N_("git psuh"), + NULL, +}; +---- + +Then, within your cmd_psuh implementation, we can declare and populate our +`option` struct. Ours is pretty boring but you can add more to it if you like: + +---- + struct option options[] = { + OPT_END() + }; +---- + +Finally, before you print your args and prefix, add the call to +`parse-options()`: + +---- + argc = parse_options(argc, argv, prefix, options, psuh_usage, 0); +---- + +This call will modify your `argv` and `options` parameters. It will strip +options you specified in `options` from `argv` and populate them in `options` +instead, if they were provided. Be sure to replace your `argc` with the result +from `parse_options`, or you will be confused if you try to parse argv later. + +It's worth noting the special argument `--`. As you may be aware, many Unix +commands use `--` to indicate "end of named parameters" - all parameters after +the `--` are interpreted merely as positional arguments. (This can be handy if +you want to pass as a parameter something which would usually be interpreted as +a flag.) `parse_options` will terminate parsing when it reaches `--` and give +you the rest of the options afterwards, untouched. + +Build again. Now, when you run with -h, you should see your usage printed and +your command terminated before anything else interesting happens. Great! + +Go ahead and commit this one, too. + +== Testing + +It's important to test your code - even for a little toy command like this one. +Moreover, your patch won't be accepted into the Git tree without tests to +demonstrate that it does what it's supposed to do. So let's add some tests. + +Related reading: `t/README` + +=== Overview of Testing Structure + +The tests in Git live in t/ and are named with a 4-decimal digit, according to +the schema shown in the Naming Tests section of `t/README`. + +=== Writing Your Test + +Since this a toy command, let's go ahead and name the test with t9999. However, +as many of the family/subcmd combinations are full, best practice seems to be +to find a command close enough to the one you've added and share its naming +space. + +Create your test script and mark it executable: + +---- +touch t/t9999-psuh-codelab.sh +chmod +x t/t9999-psuh-codelab.sh +---- + +Begin with the header as so (see +"Writing Tests" and "Source 'test-lib.sh'" in `t/README`): + +---- +#!/bin/sh + +test_description='git-psuh test + +This test runs git-psuh and makes sure it does not crash.' + +. ./test-lib.sh +---- + +Tests are framed inside of a `test_expect_success` in order to output TAP +formatted results. Begin your first test and set up the repo to test in: + +---- +test_expect_success 'runs correctly with no args' ' + rm -rf workbench upstream && + test_create_repo upstream && +---- + +`test_create_repo` comes from `test-lib.sh`. Next, we'll modify the above to +move into the new repo and run our new command: + +---- +test_expect_success 'runs correctly with no args' ' + rm -rf workbench upstream && + test_create_repo upstream && + ( + cd upstream && + git psuh + ) +' +---- + +Indicate that you've run everything you wanted by adding the following at the +bottom of your script: + +---- +test_done +---- + +You can get an idea of whether you created your new test script successfully +by running `make -C t test-lint`, which will check for things like test number +uniqueness, executable bit, and so on. + +=== Running Locally + +Let's try and run locally: + +---- +make -j$(nproc) +cd t/ && prove t9999-psuh-codelab.sh +---- + +You can run the full test suite and ensure git-psuh didn't break anything: + +---- +cd t/ +prove -j$(nproc) --shuffle t[0-9]*.sh +---- + +(You can also do this with `make test` but `prove` can run concurrently. +Shuffle randomizes the order the tests are run in, which makes them resilient +against unwanted inter-test dependencies. `prove` also makes the output nicer. + +Go ahead and commit this change, as well. + +== Getting Ready to Share + +You may have noticed already that the Git project performs its code reviews via +emailed patches, which are then applied by the maintainer when they are ready +and approved by the community. The Git project does not accept patches from +pull requests, and the patches emailed for review need to be formatted a +specific way - more to come on that soon. + +Before you send your patch off to be reviewed by the wide world, it's a good +idea to run the continuous integration build and test suites against your new +changes. You can do this manually or by using GitGitGadget, but either way, +you're going to need to fork. First thing - make sure you have a GitHub +account. + +=== Forking git/git on GitHub + +Head to the https://github.com/git/git[GitHub mirror] and look for the Fork +button. Place your fork wherever you deem appropriate and create it. + +=== Uploading To Your Own Fork + +To upload your branch to your own fork, you'll need to add the new fork as a +remote. You can use `git remote -v` to show the remotes you have added already. +From your new fork's page on GitHub, you can press "Clone or download" to get +the URL; then you need to run the following to add, replacing your own URL and +remote name for the examples provided: + +---- +git remote add remotename git@github.com:remotename/git.git +---- + +or to use the HTTPS URL: + +---- +git remote add remotename https://github.com/remotename/git/.git +---- + +Run `git remote -v` again and you should see the new remote showing up. +`git fetch remotename` (with the real name of your remote replaced) in order to +get ready to push. + +Next, double-check that you've been doing all your development in a new branch +by running `git branch`. If you didn't, now is a good time to move your new +commits to their own branch. + +As mentioned briefly at the beginning of this doc, we are basing our work on +master, so go ahead and update as shown below, or using your preferred +workflow. + +---- +git checkout master +git pull -r +git rebase master psuh +---- + +Finally, you're ready to push your new topic branch! (Due to our branch and +command name choices, be careful when you type the command below.) + +---- +git push remotename psuh +---- + +Now you should be able to go and check out your newly created branch on GitHub. + +== Sending Patches via GitGitGadget + +One option for sending patches is to follow a typical pull request workflow and +send your patches out via GitGitGadget. This section outlines the steps for this +workflow; if you'd rather use `git send-email` skip ahead. + +=== Sending a PR to GitGitGadget + +GitGitGadget is a tool created by Johannes Schindelin to make life as a Git +contributor easier for those used to the GitHub PR workflow. It allows +contributors to open pull requests against its mirror of the Git project, and +does some magic to turn the PR into a set of emails and sent them out for you. +It's documented at gitgitgadget.github.io. + +In order to have your code tested and formatted for review, you need to start by +opening a Pull Request against gitgitgadget/git. Head to +https://github.com/gitgitgadget/git and open a PR either with the "New pull +request" button or the convenient "Compare & pull request" button that may +appear with the name of your newly pushed branch. + +Review the PR's title and description, as it's used by GitGitGadget as the cover +letter for your change. When you're happy, submit your pull request. + +=== Getting CI to Run + +If it's your first time using GitGitGadget (which is likely, as you're using +this tutorial) then someone will need to give you permission to use the tool. +As mentioned in the GitGitGadget doc, you just need someone who already uses it +to comment on your PR with `/allow `. GitGitGadget will automatically +run your PRs through the CI. + +If the CI fails, you can update your changes with `rebase -i` and push your +branch again: + +---- +git push -f remotename psuh +---- + +In fact, you should continue to make changes this way up until the point when +your patch is accepted into `next`. + +//// +TODO https://github.com/gitgitgadget/gitgitgadget/issues/83 +It'd be nice to be able to verify that the patch looks good before sending it +to everyone on Git mailing list. +=== Check Your Work +//// + +=== Sending Your Patches + +Now that your CI is passing and someone has granted you permission to use +GitGitGadget with the `/allow` command, sending out for review is as simple as +commenting on your PR with `/submit`. + +=== Updating With Comments + +As documented on the GitGitGadget site, when a reviewer asks you for changes, +you can make them using `git rebase -i`. When you're ready, force push to your +fork's branch again, just like when you were getting the CI to pass above. + +NOTE: Interactive rebase can be tricky; check out this handy +https://www.oreilly.com/library/view/git-pocket-guide/9781449327507/ch10.html +[overview] from O'Reilly. + +== Sending Patches with `git send-email` + +There are a couple reasons you may not want to use GitGitGadget, such as needing +to send an RFC patch, wanting to check your work before mailing, or not having a +GitHub account. Luckily, you can use Git to mail your patches instead! + +//// +It seems like a lot of work to set up Travis to point to your own fork, and it +obviates the big reason not to use GGG - not having a GitHub account. For now, +we'll skip covering Travis with personal fork. +=== Running with Travis On Your Fork +//// + +=== Prerequisite: Setting Up `git send-email` + +Configuration for `send-email` can vary based on your operating system and email +provider, and so will not be covered in this lab, beyond stating that in many +distributions of Linux, `git-send-email` is not packaged alongside the typical +`git` install. You may need to install this additional package; there are a +number of resources online to help you do so. + +=== Preparing initial patchset + +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 -o psuh/ master..psuh +---- + +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 +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 +normal way using `git rebase -i` or by adding a new commit than by modifying a +patch. + +Check and make sure that your patches exist in the directory you specified - +you're nearly ready to send out your review! + +=== Preparing email + +In addition to an email per patch, the Git community also expects your patches +to come with a cover letter, typically with a subject line [PATCH 0/x] (where +x is the number of patches you're sending). You'll need to add some extra +parameters when you invoke `git send-email` to add the cover letter. + +---- +git send-email \ + --to=target@server.tld \ + --from=me@server.tld \ + --subject="[PATCH 0/7] adding the 'psuh' command" \ + --compose \ + psuh/ +---- + +The `--to` and `--from` fields are pretty obvious. `--subject` should indicate +that it's a cover letter with the [PATCH 0/x] tag (check how many patches you +are about to send so you can indicate the size of the thread correctly). +`--compose` indicates that you want to open an editor to write the cover letter +before sending the rest of the mails. Finally, `psuh/` attaches your directory +full of commit patches, prompting `send-email` to send one email per patch. + +When you run this, you'll get an editor so you have a chance to fill out your +cover letter. This is an important component of change submission as it explains +to the community from a high level what you're trying to do, and why, in a way +that's more apparent than just looking at your diff. Be sure to explain anything +your diff doesn't make clear on its own. + +It's also good practice to include a diffstat, which you can generate like so: + +---- +git diff --stat=72 master..psuh +---- + +The argument to `--stat` bounds the column width of the output, which is handy +as emails to Git shouldn't exceed 72 columns of width. + +Here's an example of a cover letter for `git psuh`: + +---- +Our internal metrics indicate widespread interest in the command +git-psuh - that is, many users are trying to use it, but finding it is +unavailable, using some unknown workaround instead. + +The following handful of patches add the psuh command and implement some +handy features on top of it. + +This patchset is part of the MyFirstContribution codelab and should not +be merged. + + Documentation/git-psuh.txt | 40 +++++++++++++++++++ + Makefile | 1 + + builtin.h | 1 + + builtin/psuh.c | 78 ++++++++++++++++++++++++++++++++++++++ + git.c | 1 + + t/t9999-psuh-codelab.sh | 12 ++++++ + 6 files changed, 133 insertions(+) +---- + +NOTE: When you've got a real change to send, you'll use `git@vger.kernel.org` +in the `--to` field. For now, though, don't spam the list with the codelab - +send it to yourself and check if it looks right. + +=== Sending email + +After you finish running the command above and editing your cover letter, you +will be presented with an interactive prompt for each patch that's about to go +out. This gives you one last chance to edit or quit sending something (but +again, don't edit code this way). Once you press `y` or `a` at these prompts +your emails will go out! + +Awesome, now the community will drop everything and review your changes. (Just +kidding - be patient!) + +=== Applying Changes + +Once you do have some review comments, you should make changes if necessary, or +push back on the changes by replying to the emails. (Make sure your mail client +has a plaintext email mode; the Git list rejects HTML email.) Please also follow +the mailing list etiquette outlined in the +https://kernel.googlesource.com/pub/scm/git/git/+/todo/MaintNotes[Maintainer's +Note], which are similar to etiquette rules in most open source communities +surrounding bottom-posting and inline replies. + +//// +TODO - mail list etiquette +//// + +You should apply changes using interactive rebase, or by adding new commits if +the changes seem to require it. + +NOTE: Interactive rebase can be tricky; check out this handy +https://www.oreilly.com/library/view/git-pocket-guide/9781449327507/ch10.html +[overview] from O'Reilly. + +=== Sending v2 + +When you're ready with the next iteration of your patch, the process is pretty +much the same, with a few differences: + +* When you run `format-patch`, include the argument `-v2` to add a "v2" tag to +the subject lins given. +* When you run `send-email`, include the argument `--in-reply-to=` +with the Message-Id of the cover letter of the previous version. (You can find +that Message-Id on https://public-inbox.org/git/.) Also, change the subject line +on your cover letter to include "v2" to match the subjects of your patches. + +When it's time for v3 or beyond, simply change the number above, but make sure +your v2 cover letter is in reply to your v1 cover letter, and your v3 cover +letter is in reply to your v2 cover letter, and so on. + +== Now What? + +The Git project has four integration branches: `pu`, `next`, `master`, and +`maint`. Your change will be placed into `pu` fairly early on by the maintainer +while it is still in the review process; from there, when it is ready for wider +testing, it will be merged into `next`. Plenty of early testers use `next` and +may report issues. Eventually, changes in `next` will make it to `master`, +which is typically considered stable. Finally, when a new release is cut, +`maint` is used to base bugfixes onto. As mentioned at the beginning of this +document, you can read `Documents/SubmittingPatches` for some more info about +the use of the various integration branches. + +Back to now: your code has been lauded by the upstream reviewers. It is perfect. +It is ready to be accepted. You don't need to do anything else; the maintainer +will pull your patchset into `next` and life is good. + +However, if it isn't so perfect, once it is in `next`, you can no longer modify +your commits in GitGitGadget or the email thread. Consider that review "closed" +- you will need to repeat the entire process for any bug fix commits you need +to send, basing your changes on the maintainer's topic branch for your work +instead of `master`. These topic branches are typically detailed in +https://github.com/gitster/git and are mirrored by GitGitGadget. Since they're +mirrored, you can still use GitGitGadget to send email patches, as long as +you've based your PR against the appropriate GitGitGadget/Git branch. Or, you +can use `git send-email` just the same as before, except you will generate diffs +from `..` and base your work on `` instead of `master`. diff --git a/Documentation/RelNotes/2.22.0.txt b/Documentation/RelNotes/2.22.0.txt new file mode 100644 index 00000000000000..94100fa40312b7 --- /dev/null +++ b/Documentation/RelNotes/2.22.0.txt @@ -0,0 +1,247 @@ +Git 2.22 Release Notes +====================== + +Updates since v2.21 +------------------- + +UI, Workflows & Features + + * "git checkout --no-overlay" can be used to trigger a new mode of + checking out paths out of the tree-ish, that allows paths that + match the pathspec that are in the current index and working tree + and are not in the tree-ish. + + * The %(trailers) formatter in "git log --format=..." now allows to + optionally pick trailers selectively by keyword, show only values, + etc. + + * Four new configuration variables {author,committer}.{name,email} + have been introduced to override user.{name,email} in more specific + cases. + + * Command-line completion (in contrib/) learned to tab-complete the + "git submodule absorbgitdirs" subcommand. + + * "git branch" learned a new subcommand "--show-current". + + * Output from "diff --cc" did not show the original paths when the + merge involved renames. A new option adds the paths in the + original trees to the output. + + * The command line completion (in contrib/) has been taught to + complete more subcommand parameters. + + * The final report from "git bisect" used to show the suspected + culprit using a raw "diff-tree", with which there is no output for + a merge commit. This has been updated to use a more modern and + human readable output that still is concise enough. + + * "git rebase --rebase-merges" replaces its old "--preserve-merges" + option; the latter is now marked as deprecated. + + * Error message given while cloning with --recurse-submodules has + been updated. + + * The completion helper code now pays attention to repository-local + configuration (when available), which allows --list-cmds to honour + a repository specific setting of completion.commands, for example. + + +Performance, Internal Implementation, Development Support etc. + + * The diff machinery, one of the oldest parts of the system, which + long predates the parse-options API, uses fairly long and complex + handcrafted option parser. This is being rewritten to use the + parse-options API. + + * The implementation of pack-redundant has been updated for + performance in a repository with many packfiles. + + * A more structured way to obtain execution trace has been added. + + * "git prune" has been taught to take advantage of reachability + bitmap when able. + + * The command line parser of "git commit-tree" has been rewritten to + use the parse-options API. + + * Suggest GitGitGadget instead of submitGit as a way to submit + patches based on GitHub PR to us. + + * The test framework has been updated to help developers by making it + easier to run most of the tests under different versions of + over-the-wire protocols. + + * Dev support update to make it easier to compare two formatted + results from our documentation. + + * The scripted "git rebase" implementation has been retired. + + * "git multi-pack-index verify" did not scale well with the number of + packfiles, which is being improved. + + +Fixes since v2.21 +----------------- + + * "git prune-packed" did not notice and complain against excess + arguments given from the command line, which now it does. + (merge 9b0bd87ed2 rj/prune-packed-excess-args later to maint). + + * Split-index fix. + (merge 6e37c8ed3c nd/split-index-null-base-fix later to maint). + + * "git diff --no-index" may still want to access Git goodies like + --ext-diff and --textconv, but so far these have been ignored, + which has been corrected. + (merge 287ab28bfa jk/diff-no-index-initialize later to maint). + + * Unify RPC code for smart http in protocol v0/v1 and v2, which fixes + a bug in the latter (lack of authentication retry) and generally + improves the code base. + (merge a97d00799a jt/http-auth-proto-v2-fix later to maint). + + * The include file compat/bswap.h has been updated so that it is safe + to (accidentally) include it more than once. + (merge 33aa579a55 jk/guard-bswap-header later to maint). + + * The set of header files used by "make hdr-check" unconditionally + included sha256/gcrypt.h, even when it is not used, causing the + make target to fail. We now skip it when GCRYPT_SHA256 is not in + use. + (merge f23aa18e7f rj/hdr-check-gcrypt-fix later to maint). + + * The Makefile uses 'find' utility to enumerate all the *.h header + files, which is expensive on platforms with slow filesystems; it + now optionally uses "ls-files" if working within a repository, + which is a trick similar to how all sources are enumerated to run + ETAGS on. + (merge 92b88eba9f js/find-lib-h-with-ls-files-when-possible later to maint). + + * "git rebase" that was reimplemented in C did not set ORIG_HEAD + correctly, which has been corrected. + (merge cbd29ead92 js/rebase-orig-head-fix later to maint). + + * Dev support. + (merge f545737144 js/stress-test-ui-tweak later to maint). + + * CFLAGS now can be tweaked when invoking Make while using + DEVELOPER=YesPlease; this did not work well before. + (merge 6d5d4b4e93 ab/makefile-help-devs-more later to maint). + + * "git fsck --connectivity-only" omits computation necessary to sift + the objects that are not reachable from any of the refs into + unreachable and dangling. This is now enabled when dangling + objects are requested (which is done by default, but can be + overridden with the "--no-dangling" option). + (merge 8d8c2a5aef jk/fsck-doc later to maint). + + * On platforms where "git fetch" is killed with SIGPIPE (e.g. OSX), + the upload-pack that runs on the other end that hangs up after + detecting an error could cause "git fetch" to die with a signal, + which led to a flakey test. "git fetch" now ignores SIGPIPE during + the network portion of its operation (this is not a problem as we + check the return status from our write(2)s). + (merge 143588949c jk/no-sigpipe-during-network-transport later to maint). + + * A recent update broke "is this object available to us?" check for + well-known objects like an empty tree (which should yield "yes", + even when there is no on-disk object for an empty tree), which has + been corrected. + (merge f06ab027ef jk/virtual-objects-do-exist later to maint). + + * The setup code has been cleaned up to avoid leaks around the + repository_format structure. + (merge e8805af1c3 ma/clear-repository-format later to maint). + + * "git config --type=color ..." is meant to replace "git config --get-color" + but there is a slight difference that wasn't documented, which is + now fixed. + (merge cd8e7593b9 jk/config-type-color-ends-with-lf later to maint). + + * When the "clean" filter can reduce the size of a huge file in the + working tree down to a small "token" (a la Git LFS), there is no + point in allocating a huge scratch area upfront, but the buffer is + sized based on the original file size. The convert mechanism now + allocates very minimum and reallocates as it receives the output + from the clean filter process. + (merge 02156ab031 jh/resize-convert-scratch-buffer later to maint). + + * "git rebase" uses the refs/rewritten/ hierarchy to store its + intermediate states, which inherently makes the hierarchy per + worktree, but it didn't quite work well. + (merge b9317d55a3 nd/rewritten-ref-is-per-worktree later to maint). + + * "git log -L,:" with "-s" did not suppress the patch + output as it should. This has been corrected. + (merge 05314efaea jk/line-log-with-patch later to maint). + + * "git worktree add" used to do a "find an available name with stat + and then mkdir", which is race-prone. This has been fixed by using + mkdir and reacting to EEXIST in a loop. + (merge 7af01f2367 ms/worktree-add-atomic-mkdir later to maint). + + * Build update for SHA-1 with collision detection. + (merge 07a20f569b jk/sha1dc later to maint). + + * Build procedure has been fixed around use of asciidoctor instead of + asciidoc. + (merge 185f9a0ea0 ma/asciidoctor-fixes later to maint). + + * remote-http transport did not anonymize URLs reported in its error + messages at places. + (merge c1284b21f2 js/anonymize-remote-curl-diag later to maint). + + * Error messages given from the http transport have been updated so + that they can be localized. + (merge ed8b4132c8 js/remote-curl-i18n later to maint). + + * "git init" forgot to read platform-specific repository + configuration, which made Windows port to ignore settings of + core.hidedotfiles, for example. + + * A corner-case object name ambiguity while the sequencer machinery + is working (e.g. "rebase -i -x") has been fixed. + + * "git format-patch" used overwrite an existing patch/cover-letter + file. A new "--no-clobber" option stops it. + (merge 2fe95f494c jc/format-patch-error-check later to maint). + + * "git checkout -f " while the index has an unmerged path + incorrectly left some paths in an unmerged state, which has been + corrected. + + * A corner case bug in the refs API has been corrected. + (merge d3322eb28b jk/refs-double-abort later to maint). + + * Unicode update. + (merge 584b62c37b bb/unicode-12 later to maint). + + * dumb-http walker has been updated to share more error recovery + strategy with the normal codepath. + + * Code cleanup, docfix, build fix, etc. + (merge 11f470aee7 jc/test-yes-doc later to maint). + (merge 90503a240b js/doc-symref-in-proto-v1 later to maint). + (merge 5c326d1252 jk/unused-params later to maint). + (merge 68cabbfda3 dl/doc-submodule-wo-subcommand later to maint). + (merge 9903623761 ab/receive-pack-use-after-free-fix later to maint). + (merge 1ede45e44b en/merge-options-doc later to maint). + (merge 3e14dd2c8e rd/doc-hook-used-in-sample later to maint). + (merge c271dc28fd nd/no-more-check-racy later to maint). + (merge e6e15194a8 yb/utf-16le-bom-spellfix later to maint). + (merge bb101aaf0c rd/attr.c-comment-typofix later to maint). + (merge 716a5af812 rd/gc-prune-doc-fix later to maint). + (merge 50b206371d js/untravis-windows later to maint). + (merge dbf47215e3 js/rebase-recreate-merge later to maint). + (merge 56cb2d30f8 dl/reset-doc-no-wrt-abbrev later to maint). + (merge 64eca306a2 ja/dir-rename-doc-markup-fix later to maint). + (merge af91b0230c dl/ignore-docs later to maint). + (merge 59a06e947b ra/t3600-test-path-funcs later to maint). + (merge e041d0781b ar/t4150-remove-cruft later to maint). + (merge 8d75a1d183 ma/asciidoctor-fixes-more later to maint). + (merge 74cc547b0f mh/pack-protocol-doc-fix later to maint). + (merge ed31851fa6 ab/doc-misc-typofixes later to maint). + (merge a7256debd4 nd/checkout-m-doc-update later to maint). + (merge 3a9e1ad78d jt/t5551-protocol-v2-does-not-have-half-auth later to maint). + (merge 0b918b75af sg/t5318-cleanup later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index ec8b2051450abb..6d589e118c17f7 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -372,15 +372,15 @@ such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:". Some parts of the system have dedicated maintainers with their own repositories. -- 'git-gui/' comes from git-gui project, maintained by Pat Thoyts: +- `git-gui/` comes from git-gui project, maintained by Pat Thoyts: git://repo.or.cz/git-gui.git -- 'gitk-git/' comes from Paul Mackerras's gitk project: +- `gitk-git/` comes from Paul Mackerras's gitk project: git://ozlabs.org/~paulus/gitk -- 'po/' comes from the localization coordinator, Jiang Xin: +- `po/` comes from the localization coordinator, Jiang Xin: https://github.com/git-l10n/git-po/ diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb index ec83b4959eb4d8..0089e0cfb80df9 100644 --- a/Documentation/asciidoctor-extensions.rb +++ b/Documentation/asciidoctor-extensions.rb @@ -11,12 +11,12 @@ class LinkGitProcessor < Asciidoctor::Extensions::InlineMacroProcessor def process(parent, target, attrs) if parent.document.basebackend? 'html' prefix = parent.document.attr('git-relative-html-prefix') - %(#{target}(#{attrs[1]})\n) + %(#{target}(#{attrs[1]})) elsif parent.document.basebackend? 'docbook' "\n" \ "#{target}" \ "#{attrs[1]}\n" \ - "\n" + "" end end end diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index dc41957afab25d..e7b8b5e4b87bc7 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -110,5 +110,23 @@ commit. And the default value is 40. If there are more than one `-C` options given, the argument of the last `-C` will take effect. +--ignore-rev :: + Ignore changes made by the revision when assigning blame, as if the + change never happened. Lines that were changed or added by an ignored + commit will be blamed on the previous commit that changed that line or + nearby lines. This option may be specified multiple times to ignore + more than one revision. If the `blame.markIgnoredLines` config option + is set, then lines that were changed by an ignored commit will be + marked with a `*` in the blame output. If the + `blame.maskIgnoredUnblamables` config option is set, then those lines that + we could not attribute to another revision are outputted as all zeros. + +--ignore-revs-file :: + Ignore revisions listed in `file`, one unabbreviated object name per line. + Whitespace and comments beginning with `#` are ignored. This option may be + repeated, and these files will be processed after any files specified with + the `blame.ignoreRevsFile` config option. An empty file name, `""`, will + clear the list of revs from previously processed files. + -h:: Show help message. diff --git a/Documentation/config.txt b/Documentation/config.txt index 7b3cdd1f8d95cc..24b433169b5b7c 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -426,6 +426,8 @@ include::config/submodule.txt[] include::config/tag.txt[] +include::config/trace2.txt[] + include::config/transfer.txt[] include::config/uploadarchive.txt[] diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt index 88620429eacf85..d5fd05ce816e1a 100644 --- a/Documentation/config/advice.txt +++ b/Documentation/config/advice.txt @@ -42,7 +42,8 @@ advice.*:: state in the output of linkgit:git-status[1], in the template shown when writing commit messages in linkgit:git-commit[1], and in the help message shown - by linkgit:git-checkout[1] when switching branch. + by linkgit:git-switch[1] or + linkgit:git-checkout[1] when switching branch. statusUoption:: Advise to consider using the `-u` option to linkgit:git-status[1] when the command takes more than 2 seconds to enumerate untracked @@ -62,12 +63,14 @@ advice.*:: your information is guessed from the system username and domain name. detachedHead:: - Advice shown when you used linkgit:git-checkout[1] to - move to the detach HEAD state, to instruct how to create - a local branch after the fact. + Advice shown when you used + linkgit:git-switch[1] or linkgit:git-checkout[1] + to move to the detach HEAD state, to instruct how to + create a local branch after the fact. checkoutAmbiguousRemoteBranchName:: Advice shown when the argument to - linkgit:git-checkout[1] ambiguously resolves to a + linkgit:git-checkout[1] and linkgit:git-switch[1] + ambiguously resolves to a remote tracking branch on more than one remote in situations where an unambiguous argument would have otherwise caused a remote-tracking branch to be @@ -90,4 +93,6 @@ advice.*:: waitingForEditor:: Print a message to the terminal whenever Git is waiting for editor input from the user. + nestedTag:: + Advice shown if a user attempts to recursively tag a tag object. -- diff --git a/Documentation/config/blame.txt b/Documentation/config/blame.txt index 67b5c1d1e02a44..bb6674227da1d9 100644 --- a/Documentation/config/blame.txt +++ b/Documentation/config/blame.txt @@ -19,3 +19,19 @@ blame.showEmail:: blame.showRoot:: Do not treat root commits as boundaries in linkgit:git-blame[1]. This option defaults to false. + +blame.ignoreRevsFile:: + Ignore revisions listed in the file, one unabbreviated object name per + line, in linkgit:git-blame[1]. Whitespace and comments beginning with + `#` are ignored. This option may be repeated multiple times. Empty + file names will reset the list of ignored revisions. This option will + be handled before the command line option `--ignore-revs-file`. + +blame.maskIgnoredUnblamables:: + Output an object hash of all zeros for lines that were changed by an ignored + revision and that we could not attribute to another revision in the output + of linkgit:git-blame[1]. + +blame.markIgnoredLines:: + Mark lines that were changed by an ignored revision with a '*' in the + output of linkgit:git-blame[1]. diff --git a/Documentation/config/branch.txt b/Documentation/config/branch.txt index 019d60ede2873f..a592d522a744f9 100644 --- a/Documentation/config/branch.txt +++ b/Documentation/config/branch.txt @@ -1,5 +1,5 @@ branch.autoSetupMerge:: - Tells 'git branch' and 'git checkout' to set up new branches + Tells 'git branch', 'git switch' and 'git checkout' to set up new branches so that linkgit:git-pull[1] will appropriately merge from the starting point branch. Note that even if this option is not set, this behavior can be chosen per-branch using the `--track` @@ -11,7 +11,7 @@ branch.autoSetupMerge:: branch. This option defaults to true. branch.autoSetupRebase:: - When a new branch is created with 'git branch' or 'git checkout' + When a new branch is created with 'git branch', 'git switch' or 'git checkout' that tracks another branch, this variable tells Git to set up pull to rebase instead of merge (see "branch..rebase"). When `never`, rebase is never automatically set to true. @@ -85,9 +85,9 @@ When `merges`, pass the `--rebase-merges` option to 'git rebase' so that the local merge commits are included in the rebase (see linkgit:git-rebase[1] for details). + -When preserve, also pass `--preserve-merges` along to 'git rebase' -so that locally committed merge commits will not be flattened -by running 'git pull'. +When `preserve` (deprecated in favor of `merges`), also pass +`--preserve-merges` along to 'git rebase' so that locally committed merge +commits will not be flattened by running 'git pull'. + When the value is `interactive`, the rebase is run in interactive mode. + diff --git a/Documentation/config/checkout.txt b/Documentation/config/checkout.txt index c4118fa1968711..6b646813abadc9 100644 --- a/Documentation/config/checkout.txt +++ b/Documentation/config/checkout.txt @@ -1,5 +1,6 @@ checkout.defaultRemote:: - When you run 'git checkout ' and only have one + When you run 'git checkout ' + or 'git switch ' and only have one remote, it may implicitly fall back on checking out and tracking e.g. 'origin/'. This stops working as soon as you have more than one remote with a '' @@ -8,16 +9,10 @@ checkout.defaultRemote:: disambiguation. The typical use-case is to set this to `origin`. + -Currently this is used by linkgit:git-checkout[1] when 'git checkout -' will checkout the '' branch on another remote, +Currently this is used by linkgit:git-switch[1] and +linkgit:git-checkout[1] when 'git checkout ' +or 'git switch ' +will checkout the '' branch on another remote, and by linkgit:git-worktree[1] when 'git worktree add' refers to a remote branch. This setting might be used for other checkout-like commands or functionality in the future. - -checkout.optimizeNewBranch:: - Optimizes the performance of "git checkout -b " when - using sparse-checkout. When set to true, git will not update the - repo based on the current sparse-checkout settings. This means it - will not update the skip-worktree bit in the index nor add/remove - files in the working directory to reflect the current sparse checkout - settings nor will it show the local changes. diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt index 71dce85e76926c..351b4269b7d35c 100644 --- a/Documentation/config/core.txt +++ b/Documentation/config/core.txt @@ -414,7 +414,7 @@ Common unit suffixes of 'k', 'm', or 'g' are supported. core.excludesFile:: Specifies the pathname to the file that contains patterns to describe paths that are not meant to be tracked, in addition - to '.gitignore' (per-directory) and '.git/info/exclude'. + to `.gitignore` (per-directory) and `.git/info/exclude`. Defaults to `$XDG_CONFIG_HOME/git/ignore`. If `$XDG_CONFIG_HOME` is either not set or empty, `$HOME/.config/git/ignore` is used instead. See linkgit:gitignore[5]. @@ -429,8 +429,8 @@ core.askPass:: command-line argument and write the password on its STDOUT. core.attributesFile:: - In addition to '.gitattributes' (per-directory) and - '.git/info/attributes', Git looks into this file for attributes + In addition to `.gitattributes` (per-directory) and + `.git/info/attributes`, Git looks into this file for attributes (see linkgit:gitattributes[5]). Path expansions are made the same way as for `core.excludesFile`. Its default value is `$XDG_CONFIG_HOME/git/attributes`. If `$XDG_CONFIG_HOME` is either not @@ -438,10 +438,10 @@ core.attributesFile:: core.hooksPath:: By default Git will look for your hooks in the - '$GIT_DIR/hooks' directory. Set this to different path, - e.g. '/etc/git/hooks', and Git will try to find your hooks in - that directory, e.g. '/etc/git/hooks/pre-receive' instead of - in '$GIT_DIR/hooks/pre-receive'. + `$GIT_DIR/hooks` directory. Set this to different path, + e.g. `/etc/git/hooks`, and Git will try to find your hooks in + that directory, e.g. `/etc/git/hooks/pre-receive` instead of + in `$GIT_DIR/hooks/pre-receive`. + The path can be either absolute or relative. A relative path is taken as relative to the directory where the hooks are run (see diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt index e48bb987d789e0..5afb5a2cbc69b7 100644 --- a/Documentation/config/diff.txt +++ b/Documentation/config/diff.txt @@ -10,7 +10,7 @@ diff.autoRefreshIndex:: diff.dirstat:: A comma separated list of `--dirstat` parameters specifying the - default behavior of the `--dirstat` option to linkgit:git-diff[1]` + default behavior of the `--dirstat` option to linkgit:git-diff[1] and friends. The defaults can be overridden on the command line (using `--dirstat=`). The fallback defaults (when not changed by `diff.dirstat`) are `changes,noncumulative,3`. @@ -73,12 +73,13 @@ diff.external:: environment variable. The command is called with parameters as described under "git Diffs" in linkgit:git[1]. Note: if you want to use an external diff program only on a subset of - your files, you might want to use linkgit:gitattributes[5] instead. + your files, you might want to use linkgit:gitattributes[5] instead. diff.ignoreSubmodules:: Sets the default value of --ignore-submodules. Note that this affects only 'git diff' Porcelain, and not lower level 'diff' - commands such as 'git diff-files'. 'git checkout' also honors + commands such as 'git diff-files'. 'git checkout' + and 'git switch' also honor this setting when reporting uncommitted changes. Setting it to 'all' disables the submodule summary normally shown by 'git commit' and 'git status' when `status.submoduleSummary` is set unless it is diff --git a/Documentation/config/fsck.txt b/Documentation/config/fsck.txt index 879c5a29c47ddf..450e8c38e34338 100644 --- a/Documentation/config/fsck.txt +++ b/Documentation/config/fsck.txt @@ -23,9 +23,9 @@ When `fsck.` is set, errors can be switched to warnings and vice versa by configuring the `fsck.` setting where the `` is the fsck message ID and the value is one of `error`, `warn` or `ignore`. For convenience, fsck prefixes the error/warning -with the message ID, e.g. "missingEmail: invalid author/committer line -- missing email" means that setting `fsck.missingEmail = ignore` will -hide that issue. +with the message ID, e.g. "missingEmail: invalid author/committer +line - missing email" means that setting `fsck.missingEmail = ignore` +will hide that issue. + In general, it is better to enumerate existing objects with problems with `fsck.skipList`, instead of listing the kind of breakages these diff --git a/Documentation/config/gc.txt b/Documentation/config/gc.txt index c6fbb8a96f9ee5..02b92b18b5c2cf 100644 --- a/Documentation/config/gc.txt +++ b/Documentation/config/gc.txt @@ -1,25 +1,42 @@ gc.aggressiveDepth:: The depth parameter used in the delta compression algorithm used by 'git gc --aggressive'. This defaults - to 50. + to 50, which is the default for the `--depth` option when + `--aggressive` isn't in use. ++ +See the documentation for the `--depth` option in +linkgit:git-repack[1] for more details. gc.aggressiveWindow:: The window size parameter used in the delta compression algorithm used by 'git gc --aggressive'. This defaults - to 250. + to 250, which is a much more aggressive window size than + the default `--window` of 10. ++ +See the documentation for the `--window` option in +linkgit:git-repack[1] for more details. gc.auto:: When there are approximately more than this many loose objects in the repository, `git gc --auto` will pack them. Some Porcelain commands use this command to perform a light-weight garbage collection from time to time. The - default value is 6700. Setting this to 0 disables it. + default value is 6700. ++ +Setting this to 0 disables not only automatic packing based on the +number of loose objects, but any other heuristic `git gc --auto` will +otherwise use to determine if there's work to do, such as +`gc.autoPackLimit`. gc.autoPackLimit:: When there are more than this many packs that are not marked with `*.keep` file in the repository, `git gc --auto` consolidates them into one larger pack. The - default value is 50. Setting this to 0 disables it. + default value is 50. Setting this to 0 disables it. + Setting `gc.auto` to 0 will also disable this. ++ +See the `gc.bigPackThreshold` configuration variable below. When in +use, it'll affect how the auto pack limit works. gc.autoDetach:: Make `git gc --auto` return immediately and run in background @@ -36,11 +53,16 @@ Note that if the number of kept packs is more than gc.autoPackLimit, this configuration variable is ignored, all packs except the base pack will be repacked. After this the number of packs should go below gc.autoPackLimit and gc.bigPackThreshold should be respected again. ++ +If the amount of memory estimated for `git repack` to run smoothly is +not available and `gc.bigPackThreshold` is not set, the largest pack +will also be excluded (this is the equivalent of running `git gc` with +`--keep-base-pack`). gc.writeCommitGraph:: If true, then gc will rewrite the commit-graph file when - linkgit:git-gc[1] is run. When using linkgit:git-gc[1] - '--auto' the commit-graph will be updated if housekeeping is + linkgit:git-gc[1] is run. When using `git gc --auto` + the commit-graph will be updated if housekeeping is required. Default is false. See linkgit:git-commit-graph[1] for details. @@ -94,6 +116,12 @@ gc..reflogExpireUnreachable:: With "" (e.g. "refs/stash") in the middle, the setting applies only to the refs that match the . ++ +These types of entries are generally created as a result of using `git +commit --amend` or `git rebase` and are the commits prior to the amend +or rebase occurring. Since these changes are not part of the current +project most users will want to expire them sooner, which is why the +default is more aggressive than `gc.reflogExpire`. gc.rerereResolved:: Records of conflicted merge you resolved earlier are diff --git a/Documentation/config/gpg.txt b/Documentation/config/gpg.txt index 590fe0d4baa174..f999f8ea491d02 100644 --- a/Documentation/config/gpg.txt +++ b/Documentation/config/gpg.txt @@ -16,5 +16,5 @@ gpg.format:: gpg..program:: Use this to customize the program used for the signing format you chose. (see `gpg.program` and `gpg.format`) `gpg.program` can still - be used as a legacy synonym for `gpg.openpgp.program`. The default + be used as a legacy synonym for `gpg.openpgp.program`. The default value for `gpg.x509.program` is "gpgsm". diff --git a/Documentation/config/interactive.txt b/Documentation/config/interactive.txt index ad846dd7c9906b..a2d3c7ec449e9b 100644 --- a/Documentation/config/interactive.txt +++ b/Documentation/config/interactive.txt @@ -2,7 +2,8 @@ interactive.singleKey:: In interactive commands, allow the user to provide one-letter input with a single key (i.e., without hitting enter). Currently this is used by the `--patch` mode of - linkgit:git-add[1], linkgit:git-checkout[1], linkgit:git-commit[1], + linkgit:git-add[1], linkgit:git-checkout[1], + linkgit:git-restore[1], linkgit:git-commit[1], linkgit:git-reset[1], and linkgit:git-stash[1]. Note that this setting is silently ignored if portable keystroke input is not available; requires the Perl module Term::ReadKey. diff --git a/Documentation/config/merge.txt b/Documentation/config/merge.txt index d389c739292c2d..6a313937f8c024 100644 --- a/Documentation/config/merge.txt +++ b/Documentation/config/merge.txt @@ -39,9 +39,22 @@ merge.renameLimit:: is turned off. merge.renames:: - Whether and how Git detects renames. If set to "false", - rename detection is disabled. If set to "true", basic rename - detection is enabled. Defaults to the value of diff.renames. + Whether Git detects renames. If set to "false", rename detection + is disabled. If set to "true", basic rename detection is enabled. + Defaults to the value of diff.renames. + +merge.directoryRenames:: + Whether Git detects directory renames, affecting what happens at + merge time to new files added to a directory on one side of + history when that directory was renamed on the other side of + history. If merge.directoryRenames is set to "false", directory + rename detection is disabled, meaning that such new files will be + left behind in the old directory. If set to "true", directory + rename detection is enabled, meaning that such new files will be + moved into the new directory. If set to "conflict", a conflict + will be reported for such paths. If merge.renames is false, + merge.directoryRenames is ignored and treated as false. Defaults + to "conflict". merge.renormalize:: Tell Git that canonical representation of files in the diff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt index 425c73aa521a67..9cdcfa73247842 100644 --- a/Documentation/config/pack.txt +++ b/Documentation/config/pack.txt @@ -124,6 +124,4 @@ pack.writeBitmapHashCache:: bitmapped and non-bitmapped objects (e.g., when serving a fetch between an older, bitmapped pack and objects that have been pushed since the last gc). The downside is that it consumes 4 - bytes per object of disk space, and that JGit's bitmap - implementation does not understand it, causing it to complain if - Git and JGit are used on the same repository. Defaults to false. + bytes per object of disk space. Defaults to true. diff --git a/Documentation/config/pull.txt b/Documentation/config/pull.txt index bb23a9947d78dc..b87cab31b39c44 100644 --- a/Documentation/config/pull.txt +++ b/Documentation/config/pull.txt @@ -18,9 +18,9 @@ When `merges`, pass the `--rebase-merges` option to 'git rebase' so that the local merge commits are included in the rebase (see linkgit:git-rebase[1] for details). + -When preserve, also pass `--preserve-merges` along to 'git rebase' -so that locally committed merge commits will not be flattened -by running 'git pull'. +When `preserve` (deprecated in favor of `merges`), also pass +`--preserve-merges` along to 'git rebase' so that locally committed merge +commits will not be flattened by running 'git pull'. + When the value is `interactive`, the rebase is run in interactive mode. + diff --git a/Documentation/config/rebase.txt b/Documentation/config/rebase.txt index 331d250e0468df..d98e32d812e76f 100644 --- a/Documentation/config/rebase.txt +++ b/Documentation/config/rebase.txt @@ -1,16 +1,9 @@ rebase.useBuiltin:: - Set to `false` to use the legacy shellscript implementation of - linkgit:git-rebase[1]. Is `true` by default, which means use - the built-in rewrite of it in C. -+ -The C rewrite is first included with Git version 2.20. This option -serves an an escape hatch to re-enable the legacy version in case any -bugs are found in the rewrite. This option and the shellscript version -of linkgit:git-rebase[1] will be removed in some future release. -+ -If you find some reason to set this option to `false` other than -one-off testing you should report the behavior difference as a bug in -git. + Unused configuration variable. Used in Git versions 2.20 and + 2.21 as an escape hatch to enable the legacy shellscript + implementation of rebase. Now the built-in rewrite of it in C + is always used. Setting this will emit a warning, to alert any + remaining users that setting this now does nothing. rebase.stat:: Whether to show a diffstat of what changed upstream since the last diff --git a/Documentation/config/remote.txt b/Documentation/config/remote.txt index 6c4cad83a2c9f4..a8e6437a903592 100644 --- a/Documentation/config/remote.txt +++ b/Documentation/config/remote.txt @@ -76,3 +76,11 @@ remote..pruneTags:: + See also `remote..prune` and the PRUNING section of linkgit:git-fetch[1]. + +remote..promisor:: + When set to true, this remote will be used to fetch promisor + objects. + +remote..partialclonefilter:: + The filter that will be applied when fetching from this + promisor remote. diff --git a/Documentation/config/repack.txt b/Documentation/config/repack.txt index a5c37813fdad63..9c413e177e02c6 100644 --- a/Documentation/config/repack.txt +++ b/Documentation/config/repack.txt @@ -24,4 +24,4 @@ repack.writeBitmaps:: packs created for clones and fetches, at the cost of some disk space and extra time spent on the initial repack. This has no effect if multiple packfiles are created. - Defaults to false. + Defaults to true on bare repos, false otherwise. diff --git a/Documentation/config/trace2.txt b/Documentation/config/trace2.txt new file mode 100644 index 00000000000000..a5f409c1c13c55 --- /dev/null +++ b/Documentation/config/trace2.txt @@ -0,0 +1,56 @@ +Trace2 config settings are only read from the system and global +config files; repository local and worktree config files and `-c` +command line arguments are not respected. + +trace2.normalTarget:: + This variable controls the normal target destination. + It may be overridden by the `GIT_TR2` environment variable. + The following table shows possible values. + +trace2.perfTarget:: + This variable controls the performance target destination. + It may be overridden by the `GIT_TR2_PERF` environment variable. + The following table shows possible values. + +trace2.eventTarget:: + This variable controls the event target destination. + It may be overridden by the `GIT_TR2_EVENT` environment variable. + The following table shows possible values. ++ +include::../trace2-target-values.txt[] + +trace2.normalBrief:: + Boolean. When true `time`, `filename`, and `line` fields are + omitted from normal output. May be overridden by the + `GIT_TR2_BRIEF` environment variable. Defaults to false. + +trace2.perfBrief:: + Boolean. When true `time`, `filename`, and `line` fields are + omitted from PERF output. May be overridden by the + `GIT_TR2_PERF_BRIEF` environment variable. Defaults to false. + +trace2.eventBrief:: + Boolean. When true `time`, `filename`, and `line` fields are + omitted from event output. May be overridden by the + `GIT_TR2_EVENT_BRIEF` environment variable. Defaults to false. + +trace2.eventNesting:: + Integer. Specifies desired depth of nested regions in the + event output. Regions deeper than this value will be + omitted. May be overridden by the `GIT_TR2_EVENT_NESTING` + environment variable. Defaults to 2. + +trace2.configParams:: + A comma-separated list of patterns of "important" config + settings that should be recorded in the trace2 output. + For example, `core.*,remote.*.url` would cause the trace2 + output to contain events listing each configured remote. + May be overridden by the `GIT_TR2_CONFIG_PARAMS` environment + variable. Unset by default. + +trace2.destinationDebug:: + Boolean. When true Git will print error messages when a + trace target destination cannot be opened for writing. + By default, these errors are suppressed and tracing is + silently disabled. May be overridden by the + `GIT_TR2_DST_DEBUG` environment variable. diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt index b5b2ba1199c98a..0557cbbceb8159 100644 --- a/Documentation/config/user.txt +++ b/Documentation/config/user.txt @@ -1,12 +1,19 @@ -user.email:: - Your email address to be recorded in any newly created commits. - Can be overridden by the `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_EMAIL`, and - `EMAIL` environment variables. See linkgit:git-commit-tree[1]. - user.name:: - Your full name to be recorded in any newly created commits. - Can be overridden by the `GIT_AUTHOR_NAME` and `GIT_COMMITTER_NAME` - environment variables. See linkgit:git-commit-tree[1]. +user.email:: +author.name:: +author.email:: +committer.name:: +committer.email:: + The `user.name` and `user.email` variables determine what ends + up in the `author` and `committer` field of commit + objects. + If you need the `author` or `committer` to be different, the + `author.name`, `author.email`, `committer.name` or + `committer.email` variables can be set. + Also, all of these can be overridden by the `GIT_AUTHOR_NAME`, + `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`, + `GIT_COMMITTER_EMAIL` and `EMAIL` environment variables. + See linkgit:git-commit-tree[1] for more information. user.useConfigOnly:: Instruct Git to avoid trying to guess defaults for `user.email` diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index cdcc17f0ad574b..4d846d73463c52 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -95,12 +95,26 @@ from the format described above in the following way: . there are more "src" modes and "src" sha1 . status is concatenated status characters for each parent . no optional "score" number -. single path, only for "dst" +. tab-separated pathname(s) of the file -Example: +For `-c` and `--cc`, only the destination or final path is shown even +if the file was renamed on any side of history. With +`--combined-all-paths`, the name of the path in each parent is shown +followed by the name of the path in the merge commit. + +Examples for `-c` and `--cc` without `--combined-all-paths`: +------------------------------------------------ +::100644 100644 100644 fabadb8 cc95eb0 4866510 MM desc.c +::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM bar.sh +::100644 100644 100644 e07d6c5 9042e82 ee91881 RR phooey.c +------------------------------------------------ + +Examples when `--combined-all-paths` added to either `-c` or `--cc`: ------------------------------------------------ -::100644 100644 100644 fabadb8 cc95eb0 4866510 MM describe.c +::100644 100644 100644 fabadb8 cc95eb0 4866510 MM desc.c desc.c desc.c +::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM foo.sh bar.sh bar.sh +::100644 100644 100644 e07d6c5 9042e82 ee91881 RR fooey.c fuey.c phooey.c ------------------------------------------------ Note that 'combined diff' lists only files which were modified from diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index 231105cff48d9c..f10ca410ad8a93 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -143,6 +143,19 @@ copying detection) are designed to work with diff of two Similar to two-line header for traditional 'unified' diff format, `/dev/null` is used to signal created or deleted files. ++ +However, if the --combined-all-paths option is provided, instead of a +two-line from-file/to-file you get a N+1 line from-file/to-file header, +where N is the number of parents in the merge commit + + --- a/file + --- a/file + --- a/file + +++ b/file ++ +This extended format can be useful if rename or copy detection is +active, to allow you to see the original name of the file in different +parents. 4. Chunk header format is modified to prevent people from accidentally feeding it to `patch -p1`. Combined diff format diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 554a34080d7081..09faee3b44db2e 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -36,11 +36,21 @@ endif::git-format-patch[] -U:: --unified=:: Generate diffs with lines of context instead of - the usual three. + the usual three. Implies `--patch`. ifndef::git-format-patch[] Implies `-p`. endif::git-format-patch[] +--output=:: + Output to a specific file instead of stdout. + +--output-indicator-new=:: +--output-indicator-old=:: +--output-indicator-context=:: + Specify the character used to indicate new, old or context + lines in the generated patch. Normally they are '+', '-' and + ' ' respectively. + ifndef::git-format-patch[] --raw:: ifndef::git-log[] @@ -148,6 +158,7 @@ These parameters can also be set individually with `--stat-width=`, number of modified files, as well as number of added and deleted lines. +-X[]:: --dirstat[=]:: Output the distribution of relative amount of changes for each sub-directory. The behavior of `--dirstat` can be customized by @@ -192,6 +203,12 @@ directories with less than 10% of the total amount of changed files, and accumulating child directory counts in the parent directories: `--dirstat=files,10,cumulative`. +--cumulative:: + Synonym for --dirstat=cumulative + +--dirstat-by-file[=...]:: + Synonym for --dirstat=files,param1,param2... + --summary:: Output a condensed summary of extended header information such as creations, renames and mode changes. @@ -386,6 +403,9 @@ endif::git-format-patch[] Turn off rename detection, even when the configuration file gives the default to do so. +--[no-]rename-empty:: + Whether to use empty blobs as rename source. + ifndef::git-format-patch[] --check:: Warn if changes introduce conflict markers or whitespace errors. @@ -416,7 +436,7 @@ endif::git-format-patch[] --binary:: In addition to `--full-index`, output a binary diff that - can be applied with `git-apply`. + can be applied with `git-apply`. Implies `--patch`. --abbrev[=]:: Instead of showing the full 40-byte hexadecimal object diff --git a/Documentation/doc-diff b/Documentation/doc-diff index 32c83dd26f4adf..3355be47981237 100755 --- a/Documentation/doc-diff +++ b/Documentation/doc-diff @@ -12,9 +12,16 @@ OPTIONS_SPEC="\ doc-diff [options] [-- ] doc-diff (-c|--clean) -- -j=n parallel argument to pass to make -f force rebuild; do not rely on cached results -c,clean cleanup temporary working files +j=n parallel argument to pass to make +f force rebuild; do not rely on cached results +c,clean cleanup temporary working files +from-asciidoc use asciidoc with the 'from'-commit +from-asciidoctor use asciidoctor with the 'from'-commit +asciidoc use asciidoc with both commits +to-asciidoc use asciidoc with the 'to'-commit +to-asciidoctor use asciidoctor with the 'to'-commit +asciidoctor use asciidoctor with both commits +cut-header-footer cut away header and footer " SUBDIRECTORY_OK=1 . "$(git --exec-path)/git-sh-setup" @@ -22,6 +29,9 @@ SUBDIRECTORY_OK=1 parallel= force= clean= +from_program= +to_program= +cut_header_footer= while test $# -gt 0 do case "$1" in @@ -31,6 +41,22 @@ do clean=t ;; -f) force=t ;; + --from-asciidoctor) + from_program=-asciidoctor ;; + --to-asciidoctor) + to_program=-asciidoctor ;; + --asciidoctor) + from_program=-asciidoctor + to_program=-asciidoctor ;; + --from-asciidoc) + from_program=-asciidoc ;; + --to-asciidoc) + to_program=-asciidoc ;; + --asciidoc) + from_program=-asciidoc + to_program=-asciidoc ;; + --cut-header-footer) + cut_header_footer=-cut-header-footer ;; --) shift; break ;; *) @@ -79,6 +105,22 @@ then ln -s "$dots/config.mak" "$tmp/worktree/config.mak" fi +construct_makemanflags () { + if test "$1" = "-asciidoc" + then + echo USE_ASCIIDOCTOR= + elif test "$1" = "-asciidoctor" + then + echo USE_ASCIIDOCTOR=YesPlease + fi +} + +from_makemanflags=$(construct_makemanflags "$from_program") && +to_makemanflags=$(construct_makemanflags "$to_program") && + +from_dir=$from_oid$from_program$cut_header_footer && +to_dir=$to_oid$to_program$cut_header_footer && + # generate_render_makefile generate_render_makefile () { find "$1" -type f | @@ -94,7 +136,7 @@ generate_render_makefile () { done } -# render_tree +# render_tree render_tree () { # Skip install-man entirely if we already have an installed directory. # We can't rely on make here, since "install-man" unconditionally @@ -102,28 +144,44 @@ render_tree () { # we then can't rely on during the render step). We use "mv" to make # sure we don't get confused by a previous run that failed partway # through. - if ! test -d "$tmp/installed/$1" + oid=$1 && + dname=$2 && + makemanflags=$3 && + if ! test -d "$tmp/installed/$dname" then - git -C "$tmp/worktree" checkout --detach "$1" && + git -C "$tmp/worktree" checkout --detach "$oid" && make -j$parallel -C "$tmp/worktree" \ + $makemanflags \ GIT_VERSION=omitted \ SOURCE_DATE_EPOCH=0 \ - DESTDIR="$tmp/installed/$1+" \ + DESTDIR="$tmp/installed/$dname+" \ install-man && - mv "$tmp/installed/$1+" "$tmp/installed/$1" + mv "$tmp/installed/$dname+" "$tmp/installed/$dname" fi && # As with "installed" above, we skip the render if it's already been # done. So using make here is primarily just about running in # parallel. - if ! test -d "$tmp/rendered/$1" + if ! test -d "$tmp/rendered/$dname" then - generate_render_makefile "$tmp/installed/$1" "$tmp/rendered/$1+" | + generate_render_makefile "$tmp/installed/$dname" \ + "$tmp/rendered/$dname+" | make -j$parallel -f - && - mv "$tmp/rendered/$1+" "$tmp/rendered/$1" + mv "$tmp/rendered/$dname+" "$tmp/rendered/$dname" + + if test "$cut_header_footer" = "-cut-header-footer" + then + for f in $(find "$tmp/rendered/$dname" -type f) + do + tail -n +3 "$f" | head -n -2 | + sed -e '1{/^$/d}' -e '${/^$/d}' >"$f+" && + mv "$f+" "$f" || + return 1 + done + fi fi } -render_tree $from_oid && -render_tree $to_oid && -git -C $tmp/rendered diff --no-index "$@" $from_oid $to_oid +render_tree $from_oid $from_dir $from_makemanflags && +render_tree $to_oid $to_dir $to_makemanflags && +git -C $tmp/rendered diff --no-index "$@" $from_dir $to_dir diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index fa0a3151b3f7e9..91c47752ecdc9c 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -216,7 +216,8 @@ endif::git-pull[] --server-option=