diff --git a/.cirrus.yml b/.cirrus.yml new file mode 100644 index 00000000000000..1fbdc2652b3e59 --- /dev/null +++ b/.cirrus.yml @@ -0,0 +1,22 @@ +env: + CIRRUS_CLONE_DEPTH: 1 + +freebsd_task: + env: + GIT_PROVE_OPTS: "--timer --jobs 10" + GIT_TEST_OPTS: "--no-chain-lint --no-bin-wrappers" + MAKEFLAGS: "-j4" + DEFAULT_TEST_TARGET: prove + DEVELOPER: 1 + freebsd_instance: + image_family: freebsd-13-4 + memory: 2G + install_script: + pkg install -y gettext gmake perl5 + create_user_script: + - pw useradd git + - chown -R git:git . + build_script: + - su git -c gmake + test_script: + - su git -c 'gmake DEFAULT_UNIT_TEST_TARGET=unit-tests-prove test unit-tests' diff --git a/.clang-format b/.clang-format new file mode 100644 index 00000000000000..9547fe1b77cac0 --- /dev/null +++ b/.clang-format @@ -0,0 +1,225 @@ +# This file is an example configuration for clang-format 5.0. +# +# Note that this style definition should only be understood as a hint +# for writing new code. The rules are still work-in-progress and does +# not yet exactly match the style we have in the existing code. + +# Use tabs whenever we need to fill whitespace that spans at least from one tab +# stop to the next one. +# +# These settings are mirrored in .editorconfig. Keep them in sync. +UseTab: Always +TabWidth: 8 +IndentWidth: 8 +ContinuationIndentWidth: 8 +ColumnLimit: 80 + +# C Language specifics +Language: Cpp + +# Align parameters on the open bracket +# someLongFunction(argument1, +# argument2); +AlignAfterOpenBracket: Align + +# Don't align consecutive assignments +# int aaaa = 12; +# int b = 14; +AlignConsecutiveAssignments: false + +# Don't align consecutive declarations +# int aaaa = 12; +# double b = 3.14; +AlignConsecutiveDeclarations: false + +# Align consecutive macro definitions. +AlignConsecutiveMacros: true + +# Align escaped newlines as far left as possible +# #define A \ +# int aaaa; \ +# int b; \ +# int cccccccc; +AlignEscapedNewlines: Left + +# Align operands of binary and ternary expressions +# int aaa = bbbbbbbbbbb + +# cccccc; +AlignOperands: true + +# Don't align trailing comments +# int a; // Comment a +# int b = 2; // Comment b +AlignTrailingComments: false + +# By default don't allow putting parameters onto the next line +# myFunction(foo, bar, baz); +AllowAllParametersOfDeclarationOnNextLine: false + +# Don't allow short braced statements to be on a single line +# if (a) not if (a) return; +# return; +AllowShortBlocksOnASingleLine: false +AllowShortCaseLabelsOnASingleLine: false +AllowShortFunctionsOnASingleLine: false +AllowShortIfStatementsOnASingleLine: false +AllowShortLoopsOnASingleLine: false + +# By default don't add a line break after the return type of top-level functions +# int foo(); +AlwaysBreakAfterReturnType: None + +# Pack as many parameters or arguments onto the same line as possible +# int myFunction(int aaaaaaaaaaaa, int bbbbbbbb, +# int cccc); +BinPackArguments: true +BinPackParameters: true + +# Add no space around the bit field +# unsigned bf:2; +BitFieldColonSpacing: None + +# Attach braces to surrounding context except break before braces on function +# definitions. +# void foo() +# { +# if (true) { +# } else { +# } +# }; +BreakBeforeBraces: Linux + +# Break after operators +# int value = aaaaaaaaaaaaa + +# bbbbbb - +# ccccccccccc; +BreakBeforeBinaryOperators: None +BreakBeforeTernaryOperators: false + +# Don't break string literals +BreakStringLiterals: false + +# Use the same indentation level as for the switch statement. +# Switch statement body is always indented one level more than case labels. +IndentCaseLabels: false + +# Indents directives before the hash. Each level uses a single space for +# indentation. +# #if FOO +# # include +# #endif +IndentPPDirectives: AfterHash +PPIndentWidth: 1 + +# Don't indent a function definition or declaration if it is wrapped after the +# type +IndentWrappedFunctionNames: false + +# Align pointer to the right +# int *a; +PointerAlignment: Right + +# Don't insert a space after a cast +# x = (int32)y; not x = (int32) y; +SpaceAfterCStyleCast: false + +# No space is inserted after the logical not operator +SpaceAfterLogicalNot: false + +# Insert spaces before and after assignment operators +# int a = 5; not int a=5; +# a += 42; a+=42; +SpaceBeforeAssignmentOperators: true + +# Spaces will be removed before case colon. +# case 1: break; not case 1 : break; +SpaceBeforeCaseColon: false + +# Put a space before opening parentheses only after control statement keywords. +# void f() { +# if (true) { +# f(); +# } +# } +SpaceBeforeParens: ControlStatements + +# Don't insert spaces inside empty '()' +SpaceInEmptyParentheses: false + +# No space before first '[' in arrays +# int a[5][5]; not int a [5][5]; +SpaceBeforeSquareBrackets: false + +# No space will be inserted into {} +# while (true) {} not while (true) { } +SpaceInEmptyBlock: false + +# The number of spaces before trailing line comments (// - comments). +# This does not affect trailing block comments (/* - comments). +SpacesBeforeTrailingComments: 1 + +# Don't insert spaces in casts +# x = (int32) y; not x = ( int32 ) y; +SpacesInCStyleCastParentheses: false + +# Don't insert spaces inside container literals +# var arr = [1, 2, 3]; not var arr = [ 1, 2, 3 ]; +SpacesInContainerLiterals: false + +# Don't insert spaces after '(' or before ')' +# f(arg); not f( arg ); +SpacesInParentheses: false + +# Don't insert spaces after '[' or before ']' +# int a[5]; not int a[ 5 ]; +SpacesInSquareBrackets: false + +# Insert a space after '{' and before '}' in struct initializers +Cpp11BracedListStyle: false + +# A list of macros that should be interpreted as foreach loops instead of as +# function calls. Taken from: +# git grep -h '^#define [^[:space:]]*for_\?each[^[:space:]]*(' | +# sed "s/^#define / - '/; s/(.*$/'/" | sort | uniq +ForEachMacros: + - 'for_each_builtin' + - 'for_each_string_list_item' + - 'for_each_ut' + - 'for_each_wanted_builtin' + - 'hashmap_for_each_entry' + - 'hashmap_for_each_entry_from' + - 'kh_foreach' + - 'kh_foreach_value' + - 'list_for_each' + - 'list_for_each_dir' + - 'list_for_each_prev' + - 'list_for_each_prev_safe' + - 'list_for_each_safe' + - 'strintmap_for_each_entry' + - 'strmap_for_each_entry' + - 'strset_for_each_entry' + +# A list of macros that should be interpreted as conditionals instead of as +# function calls. +IfMacros: + - 'if_test' + +# The maximum number of consecutive empty lines to keep. +MaxEmptyLinesToKeep: 1 + +# No empty line at the start of a block. +KeepEmptyLinesAtTheStartOfBlocks: false + +# Penalties +# This decides what order things should be done if a line is too long +PenaltyBreakAssignment: 5 +PenaltyBreakBeforeFirstCallParameter: 5 +PenaltyBreakComment: 5 +PenaltyBreakFirstLessLess: 0 +PenaltyBreakOpenParenthesis: 300 +PenaltyBreakString: 5 +PenaltyExcessCharacter: 10 +PenaltyReturnTypeOnItsOwnLine: 300 + +# Don't sort #include's +SortIncludes: false diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 00000000000000..15d6cbeab109ef --- /dev/null +++ b/.editorconfig @@ -0,0 +1,16 @@ +[*] +charset = utf-8 +insert_final_newline = true + +# The settings for C (*.c and *.h) files are mirrored in .clang-format. Keep +# them in sync. +[{*.{c,h,sh,perl,pl,pm,txt},config.mak.*,Makefile}] +indent_style = tab +tab_width = 8 + +[*.py] +indent_style = space +indent_size = 4 + +[COMMIT_EDITMSG] +max_line_length = 72 diff --git a/.gitattributes b/.gitattributes index 5e98806c6cc246..60d486390b91df 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,3 +1,19 @@ * whitespace=!indent,trail,space -*.[ch] whitespace=indent,trail,space -*.sh whitespace=indent,trail,space +*.[ch] whitespace=indent,trail,space diff=cpp +*.sh whitespace=indent,trail,space text eol=lf +*.perl text eol=lf diff=perl +*.pl text eof=lf diff=perl +*.pm text eol=lf diff=perl +*.py text eol=lf diff=python +*.bat text eol=crlf +*.png binary +CODE_OF_CONDUCT.md -whitespace +/Documentation/**/*.txt text eol=lf +/command-list.txt text eol=lf +/GIT-VERSION-GEN text eol=lf +/mergetools/* text eol=lf +/t/oid-info/* text eol=lf +/Documentation/git-merge.txt conflict-marker-size=32 +/Documentation/gitk.txt conflict-marker-size=32 +/Documentation/user-manual.txt conflict-marker-size=32 +/t/t????-*.sh conflict-marker-size=32 diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 00000000000000..c8755e38de81ca --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,22 @@ +## Contributing to Git + +Thanks for taking the time to contribute to Git! Please be advised that the +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 [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) +to learn how the Git project is managed, and how you can work with it. +In addition, we highly recommend you to read [our submission guidelines](../Documentation/SubmittingPatches). + +If you prefer video, then [this talk](https://www.youtube.com/watch?v=Q7i_qQW__q4&feature=youtu.be&t=6m4s) +might be useful to you as the presenter walks you through the contribution +process by example. + +Or, you can follow the ["My First Contribution"](https://git-scm.com/docs/MyFirstContribution) +tutorial for another example of the contribution process. + +Your friendly Git community! diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 00000000000000..4017ed82ca4341 --- /dev/null +++ b/.github/ISSUE_TEMPLATE.md @@ -0,0 +1,64 @@ + - [ ] I was not able to find an [open](https://github.com/git-for-windows/git/issues?q=is%3Aopen) or [closed](https://github.com/git-for-windows/git/issues?q=is%3Aclosed) issue matching what I'm seeing + +### Setup + + - Which version of Git for Windows are you using? Is it 32-bit or 64-bit? + +``` +$ git --version --build-options + +** insert your machine's response here ** +``` + + - Which version of Windows are you running? Vista, 7, 8, 10? Is it 32-bit or 64-bit? + +``` +$ cmd.exe /c ver + +** insert your machine's response here ** +``` + + - What options did you set as part of the installation? Or did you choose the + defaults? + +``` +# One of the following: +> type "C:\Program Files\Git\etc\install-options.txt" +> type "C:\Program Files (x86)\Git\etc\install-options.txt" +> type "%USERPROFILE%\AppData\Local\Programs\Git\etc\install-options.txt" +> type "$env:USERPROFILE\AppData\Local\Programs\Git\etc\install-options.txt" +$ cat /etc/install-options.txt + +** insert your machine's response here ** +``` + + - Any other interesting things about your environment that might be related + to the issue you're seeing? + +** insert your response here ** + +### Details + + - Which terminal/shell are you running Git from? e.g Bash/CMD/PowerShell/other + +** insert your response here ** + + - What commands did you run to trigger this issue? If you can provide a + [Minimal, Complete, and Verifiable example](http://stackoverflow.com/help/mcve) + this will help us understand the issue. + +``` +** insert your commands here ** +``` + - What did you expect to occur after running these commands? + +** insert here ** + + - What actually happened instead? + +** insert here ** + + - If the problem was occurring with a specific repository, can you provide the + URL to that repository to help us with testing? + +** insert URL here ** diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000000000..7baf31f2c471ec --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,22 @@ +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. + +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. + +Instead, we use the Git mailing list (git@vger.kernel.org) for code and +documentation submissions, code reviews, and bug reports. The +mailing list is plain text only (anything with HTML is sent directly +to the spam folder). + +Nevertheless, you can use GitGitGadget (https://gitgitgadget.github.io/) +to conveniently send your Pull Requests commits to our mailing list. + +For a single-commit pull request, please *leave the pull request description +empty*: your commit message itself should describe your changes. + +Please read the "guidelines for contributing" linked above! diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 00000000000000..22d5376407abf1 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,13 @@ +# To get started with Dependabot version updates, you'll need to specify which +# package ecosystems to update and where the package manifests are located. +# Please see the documentation for all configuration options: +# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file +# especially +# https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot#enabling-dependabot-version-updates-for-actions + +version: 2 +updates: + - package-ecosystem: "github-actions" # See documentation for possible values + directory: "/" # Location of package manifests + schedule: + interval: "weekly" diff --git a/.github/workflows/check-style.yml b/.github/workflows/check-style.yml new file mode 100644 index 00000000000000..c052a5df2381e9 --- /dev/null +++ b/.github/workflows/check-style.yml @@ -0,0 +1,34 @@ +name: check-style + +# Get the repository with all commits to ensure that we can analyze +# all of the commits contributed via the Pull Request. + +on: + pull_request: + types: [opened, synchronize] + +# Avoid unnecessary builds. Unlike the main CI jobs, these are not +# ci-configurable (but could be). +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + check-style: + env: + CC: clang + jobname: ClangFormat + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - run: ci/install-dependencies.sh + + - name: git clang-format + continue-on-error: true + id: check_out + run: | + ./ci/run-style-check.sh \ + "${{github.event.pull_request.base.sha}}" diff --git a/.github/workflows/check-whitespace.yml b/.github/workflows/check-whitespace.yml new file mode 100644 index 00000000000000..d0a78fc426f9e4 --- /dev/null +++ b/.github/workflows/check-whitespace.yml @@ -0,0 +1,32 @@ +name: check-whitespace + +# Get the repository with all commits to ensure that we can analyze +# all of the commits contributed via the Pull Request. +# Process `git log --check` output to extract just the check errors. +# Exit with failure upon white-space issues. + +on: + pull_request: + types: [opened, synchronize] + +# Avoid unnecessary builds. Unlike the main CI jobs, these are not +# ci-configurable (but could be). +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + check-whitespace: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: git log --check + id: check_out + run: | + ./ci/check-whitespace.sh \ + "${{github.event.pull_request.base.sha}}" \ + "$GITHUB_STEP_SUMMARY" \ + "https://github.com/${{github.repository}}" diff --git a/.github/workflows/coverity.yml b/.github/workflows/coverity.yml new file mode 100644 index 00000000000000..48341e81f49066 --- /dev/null +++ b/.github/workflows/coverity.yml @@ -0,0 +1,163 @@ +name: Coverity + +# This GitHub workflow automates submitting builds to Coverity Scan. To enable it, +# set the repository variable `ENABLE_COVERITY_SCAN_FOR_BRANCHES` (for details, see +# https://docs.github.com/en/actions/learn-github-actions/variables) to a JSON +# string array containing the names of the branches for which the workflow should be +# run, e.g. `["main", "next"]`. +# +# In addition, two repository secrets must be set (for details how to add secrets, see +# https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions): +# `COVERITY_SCAN_EMAIL` and `COVERITY_SCAN_TOKEN`. The former specifies the +# email to which the Coverity reports should be sent and the latter can be +# obtained from the Project Settings tab of the Coverity project). +# +# The workflow runs on `ubuntu-latest` by default. This can be overridden by setting +# the repository variable `ENABLE_COVERITY_SCAN_ON_OS` to a JSON string array specifying +# the operating systems, e.g. `["ubuntu-latest", "windows-latest"]`. +# +# By default, the builds are submitted to the Coverity project `git`. To override this, +# set the repository variable `COVERITY_PROJECT`. + +on: + push: + +defaults: + run: + shell: bash + +jobs: + coverity: + if: contains(fromJSON(vars.ENABLE_COVERITY_SCAN_FOR_BRANCHES || '[""]'), github.ref_name) + strategy: + matrix: + os: ${{ fromJSON(vars.ENABLE_COVERITY_SCAN_ON_OS || '["ubuntu-latest"]') }} + runs-on: ${{ matrix.os }} + env: + COVERITY_PROJECT: ${{ vars.COVERITY_PROJECT || 'git' }} + COVERITY_LANGUAGE: cxx + COVERITY_PLATFORM: overridden-below + steps: + - uses: actions/checkout@v4 + - name: install minimal Git for Windows SDK + if: contains(matrix.os, 'windows') + uses: git-for-windows/setup-git-for-windows-sdk@v1 + - run: ci/install-dependencies.sh + if: contains(matrix.os, 'ubuntu') || contains(matrix.os, 'macos') + env: + distro: ${{ matrix.os }} + + # The Coverity site says the tool is usually updated twice yearly, so the + # MD5 of download can be used to determine whether there's been an update. + - name: get the Coverity Build Tool hash + id: lookup + run: | + case "${{ matrix.os }}" in + *windows*) + COVERITY_PLATFORM=win64 + COVERITY_TOOL_FILENAME=cov-analysis.zip + MAKEFLAGS=-j$(nproc) + ;; + *macos*) + COVERITY_PLATFORM=macOSX + COVERITY_TOOL_FILENAME=cov-analysis.dmg + MAKEFLAGS=-j$(sysctl -n hw.physicalcpu) + ;; + *ubuntu*) + COVERITY_PLATFORM=linux64 + COVERITY_TOOL_FILENAME=cov-analysis.tgz + MAKEFLAGS=-j$(nproc) + ;; + *) + echo '::error::unhandled OS ${{ matrix.os }}' >&2 + exit 1 + ;; + esac + echo "COVERITY_PLATFORM=$COVERITY_PLATFORM" >>$GITHUB_ENV + echo "COVERITY_TOOL_FILENAME=$COVERITY_TOOL_FILENAME" >>$GITHUB_ENV + echo "MAKEFLAGS=$MAKEFLAGS" >>$GITHUB_ENV + MD5=$(curl https://scan.coverity.com/download/$COVERITY_LANGUAGE/$COVERITY_PLATFORM \ + --fail \ + --form token='${{ secrets.COVERITY_SCAN_TOKEN }}' \ + --form project="$COVERITY_PROJECT" \ + --form md5=1) + case $? in + 0) ;; # okay + 22) # 40x, i.e. access denied + echo "::error::incorrect token or project?" >&2 + exit 1 + ;; + *) # other error + echo "::error::Failed to retrieve MD5" >&2 + exit 1 + ;; + esac + echo "hash=$MD5" >>$GITHUB_OUTPUT + + # Try to cache the tool to avoid downloading 1GB+ on every run. + # A cache miss will add ~30s to create, but a cache hit will save minutes. + - name: restore the Coverity Build Tool + id: cache + uses: actions/cache/restore@v4 + with: + path: ${{ runner.temp }}/cov-analysis + key: cov-build-${{ env.COVERITY_LANGUAGE }}-${{ env.COVERITY_PLATFORM }}-${{ steps.lookup.outputs.hash }} + - name: download the Coverity Build Tool (${{ env.COVERITY_LANGUAGE }} / ${{ env.COVERITY_PLATFORM}}) + if: steps.cache.outputs.cache-hit != 'true' + run: | + curl https://scan.coverity.com/download/$COVERITY_LANGUAGE/$COVERITY_PLATFORM \ + --fail --no-progress-meter \ + --output $RUNNER_TEMP/$COVERITY_TOOL_FILENAME \ + --form token='${{ secrets.COVERITY_SCAN_TOKEN }}' \ + --form project="$COVERITY_PROJECT" + - name: extract the Coverity Build Tool + if: steps.cache.outputs.cache-hit != 'true' + run: | + case "$COVERITY_TOOL_FILENAME" in + *.tgz) + mkdir $RUNNER_TEMP/cov-analysis && + tar -xzf $RUNNER_TEMP/$COVERITY_TOOL_FILENAME --strip 1 -C $RUNNER_TEMP/cov-analysis + ;; + *.dmg) + cd $RUNNER_TEMP && + attach="$(hdiutil attach $COVERITY_TOOL_FILENAME)" && + volume="$(echo "$attach" | cut -f 3 | grep /Volumes/)" && + mkdir cov-analysis && + cd cov-analysis && + sh "$volume"/cov-analysis-macosx-*.sh && + ls -l && + hdiutil detach "$volume" + ;; + *.zip) + cd $RUNNER_TEMP && + mkdir cov-analysis-tmp && + unzip -d cov-analysis-tmp $COVERITY_TOOL_FILENAME && + mv cov-analysis-tmp/* cov-analysis + ;; + *) + echo "::error::unhandled archive type: $COVERITY_TOOL_FILENAME" >&2 + exit 1 + ;; + esac + - name: cache the Coverity Build Tool + if: steps.cache.outputs.cache-hit != 'true' + uses: actions/cache/save@v4 + with: + path: ${{ runner.temp }}/cov-analysis + key: cov-build-${{ env.COVERITY_LANGUAGE }}-${{ env.COVERITY_PLATFORM }}-${{ steps.lookup.outputs.hash }} + - name: build with cov-build + run: | + export PATH="$RUNNER_TEMP/cov-analysis/bin:$PATH" && + cov-configure --gcc && + cov-build --dir cov-int make + - name: package the build + run: tar -czvf cov-int.tgz cov-int + - name: submit the build to Coverity Scan + run: | + curl \ + --fail \ + --form token='${{ secrets.COVERITY_SCAN_TOKEN }}' \ + --form email='${{ secrets.COVERITY_SCAN_EMAIL }}' \ + --form file=@cov-int.tgz \ + --form version='${{ github.sha }}' \ + "https://scan.coverity.com/builds?project=$COVERITY_PROJECT" diff --git a/.github/workflows/l10n.yml b/.github/workflows/l10n.yml new file mode 100644 index 00000000000000..e2c3dbdcb50f0c --- /dev/null +++ b/.github/workflows/l10n.yml @@ -0,0 +1,111 @@ +name: git-l10n + +on: [push, pull_request_target] + +# Avoid unnecessary builds. Unlike the main CI jobs, these are not +# ci-configurable (but could be). +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + git-po-helper: + if: >- + endsWith(github.repository, '/git-po') || + contains(github.head_ref, 'l10n') || + contains(github.ref, 'l10n') + runs-on: ubuntu-latest + permissions: + pull-requests: write + steps: + - name: Setup base and head objects + id: setup-tips + run: | + if test "${{ github.event_name }}" = "pull_request_target" + then + base=${{ github.event.pull_request.base.sha }} + head=${{ github.event.pull_request.head.sha }} + else + base=${{ github.event.before }} + head=${{ github.event.after }} + fi + echo base=$base >>$GITHUB_OUTPUT + echo head=$head >>$GITHUB_OUTPUT + - name: Run partial clone + run: | + git -c init.defaultBranch=master init --bare . + git remote add \ + --mirror=fetch \ + origin \ + https://github.com/${{ github.repository }} + # Fetch tips that may be unreachable from github.ref: + # - For a forced push, "$base" may be unreachable. + # - For a "pull_request_target" event, "$head" may be unreachable. + args= + for commit in \ + ${{ steps.setup-tips.outputs.base }} \ + ${{ steps.setup-tips.outputs.head }} + do + case $commit in + *[^0]*) + args="$args $commit" + ;; + *) + # Should not fetch ZERO-OID. + ;; + esac + done + git -c protocol.version=2 fetch \ + --progress \ + --no-tags \ + --no-write-fetch-head \ + --filter=blob:none \ + origin \ + ${{ github.ref }} \ + $args + - uses: actions/setup-go@v5 + with: + go-version: '>=1.16' + cache: false + - name: Install git-po-helper + run: go install github.com/git-l10n/git-po-helper@main + - name: Install other dependencies + run: | + sudo apt-get update -q && + sudo apt-get install -q -y gettext + - name: Run git-po-helper + id: check-commits + run: | + exit_code=0 + git-po-helper check-commits \ + --github-action-event="${{ github.event_name }}" -- \ + ${{ steps.setup-tips.outputs.base }}..${{ steps.setup-tips.outputs.head }} \ + >git-po-helper.out 2>&1 || exit_code=$? + if test $exit_code -ne 0 || grep -q WARNING git-po-helper.out + then + # Remove ANSI colors which are proper for console logs but not + # proper for PR comment. + echo "COMMENT_BODY<>$GITHUB_ENV + perl -pe 's/\e\[[0-9;]*m//g; s/\bEOF$//g' git-po-helper.out >>$GITHUB_ENV + echo "EOF" >>$GITHUB_ENV + fi + cat git-po-helper.out + exit $exit_code + - name: Create comment in pull request for report + uses: mshick/add-pr-comment@v2 + if: >- + always() && + github.event_name == 'pull_request_target' && + env.COMMENT_BODY != '' + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + message: > + ${{ steps.check-commits.outcome == 'failure' && 'Errors and warnings' || 'Warnings' }} + found by [git-po-helper](https://github.com/git-l10n/git-po-helper#readme) in workflow + [#${{ github.run_number }}](${{ env.GITHUB_SERVER_URL }}/${{ github.repository }}/actions/runs/${{ github.run_id }}): + + ``` + + ${{ env.COMMENT_BODY }} + + ``` diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml new file mode 100644 index 00000000000000..b1ed3794e2b2c8 --- /dev/null +++ b/.github/workflows/main.yml @@ -0,0 +1,437 @@ +name: CI + +on: [push, pull_request] + +env: + DEVELOPER: 1 + +# If more than one workflow run is triggered for the very same commit hash +# (which happens when multiple branches pointing to the same commit), only +# the first one is allowed to run, the second will be kept in the "queued" +# state. This allows a successful completion of the first run to be reused +# in the second run via the `skip-if-redundant` logic in the `config` job. +# +# The only caveat is that if a workflow run is triggered for the same commit +# hash that another run is already being held, that latter run will be +# canceled. For more details about the `concurrency` attribute, see: +# https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#concurrency +concurrency: + group: ${{ github.sha }} + +jobs: + ci-config: + name: config + if: vars.CI_BRANCHES == '' || contains(vars.CI_BRANCHES, github.ref_name) + runs-on: ubuntu-latest + outputs: + enabled: ${{ steps.check-ref.outputs.enabled }}${{ steps.skip-if-redundant.outputs.enabled }} + skip_concurrent: ${{ steps.check-ref.outputs.skip_concurrent }} + steps: + - name: try to clone ci-config branch + run: | + git -c protocol.version=2 clone \ + --no-tags \ + --single-branch \ + -b ci-config \ + --depth 1 \ + --no-checkout \ + --filter=blob:none \ + https://github.com/${{ github.repository }} \ + config-repo && + cd config-repo && + git checkout HEAD -- ci/config || : ignore + - id: check-ref + name: check whether CI is enabled for ref + run: | + enabled=yes + if test -x config-repo/ci/config/allow-ref + then + echo "::warning::ci/config/allow-ref is deprecated; use CI_BRANCHES instead" + if ! config-repo/ci/config/allow-ref '${{ github.ref }}' + then + enabled=no + fi + fi + + skip_concurrent=yes + if test -x config-repo/ci/config/skip-concurrent && + ! config-repo/ci/config/skip-concurrent '${{ github.ref }}' + then + skip_concurrent=no + fi + echo "enabled=$enabled" >>$GITHUB_OUTPUT + echo "skip_concurrent=$skip_concurrent" >>$GITHUB_OUTPUT + - name: skip if the commit or tree was already tested + id: skip-if-redundant + uses: actions/github-script@v7 + if: steps.check-ref.outputs.enabled == 'yes' + with: + github-token: ${{secrets.GITHUB_TOKEN}} + script: | + try { + // Figure out workflow ID, commit and tree + const { data: run } = await github.rest.actions.getWorkflowRun({ + owner: context.repo.owner, + repo: context.repo.repo, + run_id: context.runId, + }); + const workflow_id = run.workflow_id; + const head_sha = run.head_sha; + const tree_id = run.head_commit.tree_id; + + // See whether there is a successful run for that commit or tree + const { data: runs } = await github.rest.actions.listWorkflowRuns({ + owner: context.repo.owner, + repo: context.repo.repo, + per_page: 500, + status: 'success', + workflow_id, + }); + for (const run of runs.workflow_runs) { + if (head_sha === run.head_sha) { + core.warning(`Successful run for the commit ${head_sha}: ${run.html_url}`); + core.setOutput('enabled', ' but skip'); + break; + } + if (run.head_commit && tree_id === run.head_commit.tree_id) { + core.warning(`Successful run for the tree ${tree_id}: ${run.html_url}`); + core.setOutput('enabled', ' but skip'); + break; + } + } + } catch (e) { + core.warning(e); + } + + windows-build: + name: win build + needs: ci-config + if: needs.ci-config.outputs.enabled == 'yes' + runs-on: windows-latest + concurrency: + group: windows-build-${{ github.ref }} + cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} + steps: + - uses: actions/checkout@v4 + - uses: git-for-windows/setup-git-for-windows-sdk@v1 + - name: build + shell: bash + env: + HOME: ${{runner.workspace}} + NO_PERL: 1 + run: . /etc/profile && ci/make-test-artifacts.sh artifacts + - name: zip up tracked files + run: git archive -o artifacts/tracked.tar.gz HEAD + - name: upload tracked files and build artifacts + uses: actions/upload-artifact@v4 + with: + name: windows-artifacts + path: artifacts + windows-test: + name: win test + runs-on: windows-latest + needs: [ci-config, windows-build] + strategy: + fail-fast: false + matrix: + nr: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] + concurrency: + group: windows-test-${{ matrix.nr }}-${{ github.ref }} + cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} + steps: + - name: download tracked files and build artifacts + uses: actions/download-artifact@v4 + with: + name: windows-artifacts + path: ${{github.workspace}} + - name: extract tracked files and build artifacts + shell: bash + run: tar xf artifacts.tar.gz && tar xf tracked.tar.gz + - uses: git-for-windows/setup-git-for-windows-sdk@v1 + - name: test + shell: bash + run: . /etc/profile && ci/run-test-slice.sh ${{matrix.nr}} 10 + - name: print test failures + if: failure() && env.FAILED_TEST_ARTIFACTS != '' + shell: bash + run: ci/print-test-failures.sh + - name: Upload failed tests' directories + if: failure() && env.FAILED_TEST_ARTIFACTS != '' + uses: actions/upload-artifact@v4 + with: + name: failed-tests-windows-${{ matrix.nr }} + path: ${{env.FAILED_TEST_ARTIFACTS}} + vs-build: + name: win+VS build + needs: ci-config + if: github.event.repository.owner.login == 'git-for-windows' && needs.ci-config.outputs.enabled == 'yes' + env: + NO_PERL: 1 + GIT_CONFIG_PARAMETERS: "'user.name=CI' 'user.email=ci@git'" + runs-on: windows-latest + strategy: + matrix: + arch: [x64, arm64] + concurrency: + group: vs-build-${{ github.ref }}-${{ matrix.arch }} + cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} + steps: + - uses: actions/checkout@v4 + - uses: git-for-windows/setup-git-for-windows-sdk@v1 + - name: initialize vcpkg + uses: actions/checkout@v4 + with: + repository: 'microsoft/vcpkg' + path: 'compat/vcbuild/vcpkg' + - name: download vcpkg artifacts + uses: git-for-windows/get-azure-pipelines-artifact@v0 + with: + repository: git/git + definitionId: 9 + - name: add msbuild to PATH + uses: microsoft/setup-msbuild@v2 + - name: copy dlls to root + shell: cmd + run: compat\vcbuild\vcpkg_copy_dlls.bat release ${{ matrix.arch }}-windows + - name: generate Visual Studio solution + shell: bash + run: | + cmake `pwd`/contrib/buildsystems/ -DCMAKE_PREFIX_PATH=`pwd`/compat/vcbuild/vcpkg/installed/${{ matrix.arch }}-windows \ + -DNO_GETTEXT=YesPlease -DPERL_TESTS=OFF -DPYTHON_TESTS=OFF -DCURL_NO_CURL_CMAKE=ON -DCMAKE_GENERATOR_PLATFORM=${{ matrix.arch }} -DVCPKG_ARCH=${{ matrix.arch }}-windows -DHOST_CPU=${{ matrix.arch }} + - name: MSBuild + run: msbuild git.sln -property:Configuration=Release -property:Platform=${{ matrix.arch }} -maxCpuCount:4 -property:PlatformToolset=v142 + - name: bundle artifact tar + shell: bash + env: + MSVC: 1 + VCPKG_ROOT: ${{github.workspace}}\compat\vcbuild\vcpkg + run: | + mkdir -p artifacts && + eval "$(make -n artifacts-tar INCLUDE_DLLS_IN_ARTIFACTS=YesPlease ARTIFACTS_DIRECTORY=artifacts NO_GETTEXT=YesPlease 2>&1 | grep ^tar)" + - name: zip up tracked files + run: git archive -o artifacts/tracked.tar.gz HEAD + - name: upload tracked files and build artifacts + uses: actions/upload-artifact@v4 + with: + name: vs-artifacts-${{ matrix.arch }} + path: artifacts + vs-test: + name: win+VS test + runs-on: windows-latest + needs: [ci-config, vs-build] + strategy: + fail-fast: false + matrix: + nr: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] + concurrency: + group: vs-test-${{ matrix.nr }}-${{ github.ref }} + cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} + steps: + - uses: git-for-windows/setup-git-for-windows-sdk@v1 + - name: download tracked files and build artifacts + uses: actions/download-artifact@v4 + with: + name: vs-artifacts-x64 + path: ${{github.workspace}} + - name: extract tracked files and build artifacts + shell: bash + run: tar xf artifacts.tar.gz && tar xf tracked.tar.gz + - name: test + shell: bash + env: + NO_SVN_TESTS: 1 + run: . /etc/profile && ci/run-test-slice.sh ${{matrix.nr}} 10 + - name: print test failures + if: failure() && env.FAILED_TEST_ARTIFACTS != '' + shell: bash + run: ci/print-test-failures.sh + - name: Upload failed tests' directories + if: failure() && env.FAILED_TEST_ARTIFACTS != '' + uses: actions/upload-artifact@v4 + with: + name: failed-tests-windows-vs-${{ matrix.nr }} + path: ${{env.FAILED_TEST_ARTIFACTS}} + regular: + name: ${{matrix.vector.jobname}} (${{matrix.vector.pool}}) + needs: ci-config + if: needs.ci-config.outputs.enabled == 'yes' + concurrency: + group: ${{ matrix.vector.jobname }}-${{ matrix.vector.pool }}-${{ github.ref }} + cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} + strategy: + fail-fast: false + matrix: + vector: + - jobname: linux-sha256 + cc: clang + pool: ubuntu-latest + - jobname: linux-reftable + cc: clang + pool: ubuntu-latest + - jobname: linux-gcc + cc: gcc + cc_package: gcc-8 + pool: ubuntu-20.04 + - jobname: linux-TEST-vars + cc: gcc + cc_package: gcc-8 + pool: ubuntu-20.04 + - jobname: osx-clang + cc: clang + pool: macos-13 + - jobname: osx-reftable + cc: clang + pool: macos-13 + - jobname: osx-gcc + cc: gcc-13 + pool: macos-13 + - jobname: osx-meson + cc: clang + pool: macos-13 + - jobname: linux-gcc-default + cc: gcc + pool: ubuntu-latest + - jobname: linux-leaks + cc: gcc + pool: ubuntu-latest + - jobname: linux-reftable-leaks + cc: gcc + pool: ubuntu-latest + - jobname: linux-asan-ubsan + cc: clang + pool: ubuntu-latest + - jobname: linux-meson + cc: gcc + pool: ubuntu-latest + env: + CC: ${{matrix.vector.cc}} + CC_PACKAGE: ${{matrix.vector.cc_package}} + jobname: ${{matrix.vector.jobname}} + distro: ${{matrix.vector.pool}} + TEST_OUTPUT_DIRECTORY: ${{github.workspace}}/t + runs-on: ${{matrix.vector.pool}} + steps: + - uses: actions/checkout@v4 + - run: ci/install-dependencies.sh + - run: ci/run-build-and-tests.sh + - name: print test failures + if: failure() && env.FAILED_TEST_ARTIFACTS != '' + run: ci/print-test-failures.sh + - name: Upload failed tests' directories + if: failure() && env.FAILED_TEST_ARTIFACTS != '' + uses: actions/upload-artifact@v4 + with: + name: failed-tests-${{matrix.vector.jobname}} + path: ${{env.FAILED_TEST_ARTIFACTS}} + fuzz-smoke-test: + name: fuzz smoke test + needs: ci-config + if: needs.ci-config.outputs.enabled == 'yes' + env: + CC: clang + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: ci/install-dependencies.sh + - run: ci/run-build-and-minimal-fuzzers.sh + dockerized: + name: ${{matrix.vector.jobname}} (${{matrix.vector.image}}) + needs: ci-config + if: needs.ci-config.outputs.enabled == 'yes' + concurrency: + group: dockerized-${{ matrix.vector.jobname }}-${{ matrix.vector.image }}-${{ github.ref }} + cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} + strategy: + fail-fast: false + matrix: + vector: + - jobname: linux-musl + image: alpine + distro: alpine-latest + # Supported until 2025-04-02. + - jobname: linux32 + image: i386/ubuntu:focal + distro: ubuntu32-20.04 + - jobname: pedantic + image: fedora + distro: fedora-latest + # A RHEL 8 compatible distro. Supported until 2029-05-31. + - jobname: almalinux-8 + image: almalinux:8 + distro: almalinux-8 + # Supported until 2026-08-31. + - jobname: debian-11 + image: debian:11 + distro: debian-11 + env: + jobname: ${{matrix.vector.jobname}} + distro: ${{matrix.vector.distro}} + runs-on: ubuntu-latest + container: ${{matrix.vector.image}} + steps: + - name: prepare libc6 for actions + if: matrix.vector.jobname == 'linux32' + run: apt -q update && apt -q -y install libc6-amd64 lib64stdc++6 + - uses: actions/checkout@v4 + - run: ci/install-dependencies.sh + - run: ci/run-build-and-tests.sh + - name: print test failures + if: failure() && env.FAILED_TEST_ARTIFACTS != '' + run: ci/print-test-failures.sh + - name: Upload failed tests' directories + if: failure() && env.FAILED_TEST_ARTIFACTS != '' + uses: actions/upload-artifact@v4 + with: + name: failed-tests-${{matrix.vector.jobname}} + path: ${{env.FAILED_TEST_ARTIFACTS}} + static-analysis: + needs: ci-config + if: needs.ci-config.outputs.enabled == 'yes' + env: + jobname: StaticAnalysis + runs-on: ubuntu-22.04 + concurrency: + group: static-analysis-${{ github.ref }} + cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} + steps: + - uses: actions/checkout@v4 + - run: ci/install-dependencies.sh + - run: ci/run-static-analysis.sh + - run: ci/check-directional-formatting.bash + sparse: + needs: ci-config + if: needs.ci-config.outputs.enabled == 'yes' + env: + jobname: sparse + runs-on: ubuntu-20.04 + concurrency: + group: sparse-${{ github.ref }} + cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} + steps: + - name: Download a current `sparse` package + # Ubuntu's `sparse` version is too old for us + uses: git-for-windows/get-azure-pipelines-artifact@v0 + with: + repository: git/git + definitionId: 10 + artifact: sparse-20.04 + - name: Install the current `sparse` package + run: sudo dpkg -i sparse-20.04/sparse_*.deb + - uses: actions/checkout@v4 + - name: Install other dependencies + run: ci/install-dependencies.sh + - run: make sparse + documentation: + name: documentation + needs: ci-config + if: needs.ci-config.outputs.enabled == 'yes' + concurrency: + group: documentation-${{ github.ref }} + cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} + env: + jobname: Documentation + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: ci/install-dependencies.sh + - run: ci/test-documentation.sh diff --git a/.github/workflows/monitor-components.yml b/.github/workflows/monitor-components.yml new file mode 100644 index 00000000000000..fedc6add69a9e0 --- /dev/null +++ b/.github/workflows/monitor-components.yml @@ -0,0 +1,98 @@ +name: Monitor component updates + +# Git for Windows is a slightly modified subset of MSYS2. Some of its +# components are maintained by Git for Windows, others by MSYS2. To help +# keeping the former up to date, this workflow monitors the Atom/RSS feeds +# and opens new tickets for each new component version. + +on: + schedule: + - cron: "23 8,11,14,17 * * *" + workflow_dispatch: + +env: + CHARACTER_LIMIT: 5000 + MAX_AGE: 7d + +jobs: + job: + # Only run this in Git for Windows' fork + if: github.event.repository.owner.login == 'git-for-windows' + runs-on: ubuntu-latest + permissions: + issues: write + strategy: + matrix: + component: + - label: git + feed: https://github.com/git/git/tags.atom + - label: git-lfs + feed: https://github.com/git-lfs/git-lfs/tags.atom + - label: git-credential-manager + feed: https://github.com/git-ecosystem/git-credential-manager/tags.atom + - label: tig + feed: https://github.com/jonas/tig/tags.atom + - label: cygwin + feed: https://github.com/cygwin/cygwin/releases.atom + title-pattern: ^(?!.*newlib) + - label: msys2-runtime-package + feed: https://github.com/msys2/MSYS2-packages/commits/master/msys2-runtime.atom + - label: msys2-runtime + feed: https://github.com/msys2/msys2-runtime/commits/HEAD.atom + aggregate: true + - label: openssh + feed: https://github.com/openssh/openssh-portable/tags.atom + - label: libfido2 + feed: https://github.com/Yubico/libfido2/tags.atom + - label: libcbor + feed: https://github.com/PJK/libcbor/tags.atom + - label: openssl + feed: https://github.com/openssl/openssl/tags.atom + title-pattern: ^(?!.*alpha) + - label: gnutls + feed: https://gnutls.org/news.atom + - label: heimdal + feed: https://github.com/heimdal/heimdal/tags.atom + - label: git-sizer + feed: https://github.com/github/git-sizer/tags.atom + - label: gitflow + feed: https://github.com/petervanderdoes/gitflow-avh/tags.atom + - label: curl + feed: https://github.com/curl/curl/tags.atom + - label: libgpg-error + feed: https://github.com/gpg/libgpg-error/releases.atom + title-pattern: ^libgpg-error-[0-9\.]*$ + - label: libgcrypt + feed: https://github.com/gpg/libgcrypt/releases.atom + title-pattern: ^libgcrypt-[0-9\.]*$ + - label: gpg + feed: https://github.com/gpg/gnupg/releases.atom + - label: mintty + feed: https://github.com/mintty/mintty/releases.atom + - label: 7-zip + feed: https://sourceforge.net/projects/sevenzip/rss?path=/7-Zip + aggregate: true + - label: bash + feed: https://git.savannah.gnu.org/cgit/bash.git/atom/?h=master + aggregate: true + - label: perl + feed: https://github.com/Perl/perl5/tags.atom + title-pattern: ^(?!.*(5\.[0-9]+[13579]|RC)) + - label: pcre2 + feed: https://github.com/PCRE2Project/pcre2/tags.atom + - label: mingw-w64-llvm + feed: https://github.com/msys2/MINGW-packages/commits/master/mingw-w64-llvm.atom + - label: innosetup + feed: https://github.com/jrsoftware/issrc/tags.atom + fail-fast: false + steps: + - uses: git-for-windows/rss-to-issues@v0 + with: + feed: ${{matrix.component.feed}} + prefix: "[New ${{matrix.component.label}} version]" + labels: component-update + github-token: ${{ secrets.GITHUB_TOKEN }} + character-limit: ${{ env.CHARACTER_LIMIT }} + max-age: ${{ env.MAX_AGE }} + aggregate: ${{matrix.component.aggregate}} + title-pattern: ${{matrix.component.title-pattern}} diff --git a/.github/workflows/nano-server.yml b/.github/workflows/nano-server.yml new file mode 100644 index 00000000000000..3d943c23d2616d --- /dev/null +++ b/.github/workflows/nano-server.yml @@ -0,0 +1,76 @@ +name: Windows Nano Server tests + +on: + workflow_dispatch: + +env: + DEVELOPER: 1 + +jobs: + test-nano-server: + runs-on: windows-2022 + env: + WINDBG_DIR: "C:/Program Files (x86)/Windows Kits/10/Debuggers/x64" + IMAGE: mcr.microsoft.com/powershell:nanoserver-ltsc2022 + + steps: + - uses: actions/checkout@v4 + - uses: git-for-windows/setup-git-for-windows-sdk@v1 + - name: build Git + shell: bash + run: make -j15 + - name: pull nanoserver image + shell: bash + run: docker pull $IMAGE + - name: run nano-server test + shell: bash + run: | + docker run \ + --user "ContainerAdministrator" \ + -v "$WINDBG_DIR:C:/dbg" \ + -v "$(cygpath -aw /mingw64/bin):C:/mingw64-bin" \ + -v "$(cygpath -aw .):C:/test" \ + $IMAGE pwsh.exe -Command ' + # Extend the PATH to include the `.dll` files in /mingw64/bin/ + $env:PATH += ";C:\mingw64-bin" + + # For each executable to test pick some no-operation set of + # flags/subcommands or something that should quickly result in an + # error with known exit code that is not a negative 32-bit + # number, and set the expected return code appropriately. + # + # Only test executables that could be expected to run in a UI + # less environment. + # + # ( Executable path, arguments, expected return code ) + # also note space is required before close parenthesis (a + # powershell quirk when defining nested arrays like this) + + $executables_to_test = @( + ("C:\test\git.exe", "", 1 ), + ("C:\test\scalar.exe", "version", 0 ) + ) + + foreach ($executable in $executables_to_test) + { + Write-Output "Now testing $($executable[0])" + &$executable[0] $executable[1] + if ($LASTEXITCODE -ne $executable[2]) { + # if we failed, run the debugger to find out what function + # or DLL could not be found and then exit the script with + # failure The missing DLL or EXE will be referenced near + # the end of the output + + # Set a flag to have the debugger show loader stub + # diagnostics. This requires running as administrator, + # otherwise the flag will be ignored. + C:\dbg\gflags -i $executable[0] +SLS + + C:\dbg\cdb.exe -c "g" -c "q" $executable[0] $executable[1] + + exit 1 + } + } + + exit 0 + ' diff --git a/.gitignore b/.gitignore index 81e12c0621d42b..9dd1fbc61e6c82 100644 --- a/.gitignore +++ b/.gitignore @@ -1,25 +1,29 @@ +/fuzz_corpora +/GIT-BUILD-DIR /GIT-BUILD-OPTIONS /GIT-CFLAGS /GIT-LDFLAGS /GIT-PREFIX /GIT-PERL-DEFINES +/GIT-PERL-HEADER /GIT-PYTHON-VARS /GIT-SCRIPT-DEFINES +/GIT-SPATCH-DEFINES +/GIT-TEST-SUITES /GIT-USER-AGENT /GIT-VERSION-FILE -/bin-wrappers/ /git /git-add -/git-add--interactive /git-am /git-annotate /git-apply /git-archimport /git-archive +/git-backfill /git-bisect -/git-bisect--helper /git-blame /git-branch +/git-bugreport /git-bundle /git-cat-file /git-check-attr @@ -27,6 +31,7 @@ /git-check-mailmap /git-check-ref-format /git-checkout +/git-checkout--worker /git-checkout-index /git-cherry /git-cherry-pick @@ -34,6 +39,7 @@ /git-clone /git-column /git-commit +/git-commit-graph /git-commit-tree /git-config /git-count-objects @@ -45,6 +51,7 @@ /git-cvsimport /git-cvsserver /git-daemon +/git-diagnose /git-diff /git-diff-files /git-diff-index @@ -59,14 +66,17 @@ /git-filter-branch /git-fmt-merge-msg /git-for-each-ref +/git-for-each-repo /git-format-patch /git-fsck /git-fsck-objects +/git-fsmonitor--daemon /git-gc /git-get-tar-commit-id /git-grep /git-hash-object /git-help +/git-hook /git-http-backend /git-http-fetch /git-http-push @@ -74,6 +84,7 @@ /git-index-pack /git-init /git-init-db +/git-interpret-trailers /git-instaweb /git-log /git-ls-files @@ -81,6 +92,7 @@ /git-ls-tree /git-mailinfo /git-mailsplit +/git-maintenance /git-merge /git-merge-base /git-merge-index @@ -96,28 +108,26 @@ /git-mergetool--lib /git-mktag /git-mktree -/git-name-rev +/git-multi-pack-index /git-mv +/git-name-rev /git-notes /git-p4 /git-pack-redundant /git-pack-objects /git-pack-refs -/git-parse-remote /git-patch-id /git-prune /git-prune-packed /git-pull /git-push /git-quiltimport +/git-range-diff /git-read-tree /git-rebase -/git-rebase--am -/git-rebase--interactive -/git-rebase--merge /git-receive-pack /git-reflog -/git-relink +/git-refs /git-remote /git-remote-http /git-remote-https @@ -125,14 +135,13 @@ /git-remote-ftps /git-remote-fd /git-remote-ext -/git-remote-testgit -/git-remote-testpy -/git-remote-testsvn /git-repack /git-replace +/git-replay /git-request-pull /git-rerere /git-reset +/git-restore /git-rev-list /git-rev-parse /git-revert @@ -142,19 +151,23 @@ /git-sh-i18n /git-sh-i18n--envsubst /git-sh-setup -/git-sh-i18n /git-shell /git-shortlog /git-show /git-show-branch /git-show-index /git-show-ref +/git-sparse-checkout /git-stage /git-stash /git-status /git-stripspace /git-submodule +/git-submodule--helper +/git-subtree +/git-survey /git-svn +/git-switch /git-symbolic-ref /git-tag /git-unpack-file @@ -168,50 +181,32 @@ /git-verify-commit /git-verify-pack /git-verify-tag +/git-version /git-web--browse /git-whatchanged +/git-worktree /git-write-tree +/scalar /git-core-*/?* +/git.res /gitweb/GITWEB-BUILD-OPTIONS /gitweb/gitweb.cgi /gitweb/static/gitweb.js /gitweb/static/gitweb.min.* -/test-chmtime -/test-ctype -/test-date -/test-delta -/test-dump-cache-tree -/test-dump-split-index -/test-scrap-cache-tree -/test-genrandom -/test-hashmap -/test-index-version -/test-line-buffer -/test-match-trees -/test-mergesort -/test-mktemp -/test-parse-options -/test-path-utils -/test-prio-queue -/test-read-cache -/test-regex -/test-revision-walking -/test-run-command -/test-sha1 -/test-sigchain -/test-string-list -/test-subprocess -/test-svn-fe -/test-urlmatch-normalization -/test-wildmatch -/common-cmds.h +/config-list.h +/command-list.h +/hook-list.h +/version-def.h *.tar.gz *.dsc *.deb +/git.rc /git.spec *.exe *.[aos] +*.o.json *.py[co] +.build/ .depend/ *.gcda *.gcno @@ -228,19 +223,33 @@ /config.mak.autogen /config.mak.append /configure -/unicode +/.vscode/ /tags /TAGS /cscope* +/compile_commands.json +/.cache/ +*.hcc *.obj *.lib -*.res *.sln +*.sp *.suo *.ncb *.vcproj *.user *.idb *.pdb -/Debug/ -/Release/ +*.ilk +*.iobj +*.ipdb +*.dll +.vs/ +Debug/ +Release/ +/UpgradeLog*.htm +/git.VC.VC.opendb +/git.VC.db +*.dSYM +/contrib/buildsystems/out +CMakeSettings.json diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml new file mode 100644 index 00000000000000..9254e01583306e --- /dev/null +++ b/.gitlab-ci.yml @@ -0,0 +1,220 @@ +default: + timeout: 2h + +stages: + - build + - test + - analyze + +workflow: + rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" + - if: $CI_COMMIT_TAG + - if: $CI_COMMIT_REF_PROTECTED == "true" + +test:linux: + image: $image + stage: test + needs: [ ] + tags: + - saas-linux-medium-amd64 + variables: + CUSTOM_PATH: "/custom" + TEST_OUTPUT_DIRECTORY: "/tmp/test-output" + before_script: + - ./ci/install-dependencies.sh + script: + - useradd builder --create-home + - chown -R builder "${CI_PROJECT_DIR}" + - sudo --preserve-env --set-home --user=builder ./ci/run-build-and-tests.sh + after_script: + - | + if test "$CI_JOB_STATUS" != 'success' + then + sudo --preserve-env --set-home --user=builder ./ci/print-test-failures.sh + mv "$TEST_OUTPUT_DIRECTORY"/failed-test-artifacts t/ + fi + parallel: + matrix: + - jobname: linux-old + image: ubuntu:20.04 + CC: gcc + - jobname: linux-sha256 + image: ubuntu:latest + CC: clang + - jobname: linux-reftable + image: ubuntu:latest + CC: clang + - jobname: linux-gcc + image: ubuntu:20.04 + CC: gcc + CC_PACKAGE: gcc-8 + - jobname: linux-TEST-vars + image: ubuntu:20.04 + CC: gcc + CC_PACKAGE: gcc-8 + - jobname: linux-gcc-default + image: ubuntu:latest + CC: gcc + - jobname: linux-leaks + image: ubuntu:latest + CC: gcc + - jobname: linux-reftable-leaks + image: ubuntu:latest + CC: gcc + - jobname: linux-asan-ubsan + image: ubuntu:latest + CC: clang + - jobname: pedantic + image: fedora:latest + - jobname: linux-musl + image: alpine:latest + - jobname: linux-meson + image: ubuntu:latest + CC: gcc + artifacts: + paths: + - t/failed-test-artifacts + when: on_failure + +test:osx: + image: $image + stage: test + needs: [ ] + tags: + - saas-macos-medium-m1 + variables: + TEST_OUTPUT_DIRECTORY: "/Volumes/RAMDisk" + before_script: + # Create a 4GB RAM disk that we use to store test output on. This small hack + # significantly speeds up tests by more than a factor of 2 because the + # macOS runners use network-attached storage as disks, which is _really_ + # slow with the many small writes that our tests do. + - sudo diskutil apfs create $(hdiutil attach -nomount ram://8192000) RAMDisk + - ./ci/install-dependencies.sh + script: + - ./ci/run-build-and-tests.sh + after_script: + - | + if test "$CI_JOB_STATUS" != 'success' + then + ./ci/print-test-failures.sh + mv "$TEST_OUTPUT_DIRECTORY"/failed-test-artifacts t/ + fi + parallel: + matrix: + - jobname: osx-clang + image: macos-14-xcode-15 + CC: clang + - jobname: osx-reftable + image: macos-14-xcode-15 + CC: clang + - jobname: osx-meson + image: macos-14-xcode-15 + CC: clang + artifacts: + paths: + - t/failed-test-artifacts + when: on_failure + +build:mingw64: + stage: build + tags: + - saas-windows-medium-amd64 + variables: + NO_PERL: 1 + before_script: + - ./ci/install-sdk.ps1 -directory "git-sdk" + script: + - git-sdk/usr/bin/bash.exe -l -c 'ci/make-test-artifacts.sh artifacts' + artifacts: + paths: + - artifacts + - git-sdk + +test:mingw64: + stage: test + tags: + - saas-windows-medium-amd64 + needs: + - job: "build:mingw64" + artifacts: true + before_script: + - git-sdk/usr/bin/bash.exe -l -c 'tar xf artifacts/artifacts.tar.gz' + - New-Item -Path .git/info -ItemType Directory + - New-Item .git/info/exclude -ItemType File -Value "/git-sdk" + script: + - git-sdk/usr/bin/bash.exe -l -c "ci/run-test-slice.sh $CI_NODE_INDEX $CI_NODE_TOTAL" + after_script: + - git-sdk/usr/bin/bash.exe -l -c 'ci/print-test-failures.sh' + parallel: 10 + +test:fuzz-smoke-tests: + image: ubuntu:latest + stage: test + needs: [ ] + variables: + CC: clang + before_script: + - ./ci/install-dependencies.sh + script: + - ./ci/run-build-and-minimal-fuzzers.sh + +static-analysis: + image: ubuntu:22.04 + stage: analyze + needs: [ ] + variables: + jobname: StaticAnalysis + before_script: + - ./ci/install-dependencies.sh + script: + - ./ci/run-static-analysis.sh + - ./ci/check-directional-formatting.bash + +check-whitespace: + image: ubuntu:latest + stage: analyze + needs: [ ] + before_script: + - ./ci/install-dependencies.sh + # Since $CI_MERGE_REQUEST_TARGET_BRANCH_SHA is only defined for merged + # pipelines, we fallback to $CI_MERGE_REQUEST_DIFF_BASE_SHA, which should + # be defined in all pipelines. + script: + - | + R=${CI_MERGE_REQUEST_TARGET_BRANCH_SHA-${CI_MERGE_REQUEST_DIFF_BASE_SHA:?}} || exit + ./ci/check-whitespace.sh "$R" + rules: + - if: $CI_PIPELINE_SOURCE == 'merge_request_event' + +check-style: + image: ubuntu:latest + stage: analyze + needs: [ ] + allow_failure: true + variables: + CC: clang + jobname: ClangFormat + before_script: + - ./ci/install-dependencies.sh + # Since $CI_MERGE_REQUEST_TARGET_BRANCH_SHA is only defined for merged + # pipelines, we fallback to $CI_MERGE_REQUEST_DIFF_BASE_SHA, which should + # be defined in all pipelines. + script: + - | + R=${CI_MERGE_REQUEST_TARGET_BRANCH_SHA-${CI_MERGE_REQUEST_DIFF_BASE_SHA:?}} || exit + ./ci/run-style-check.sh "$R" + rules: + - if: $CI_PIPELINE_SOURCE == 'merge_request_event' + +documentation: + image: ubuntu:latest + stage: analyze + needs: [ ] + variables: + jobname: Documentation + before_script: + - ./ci/install-dependencies.sh + script: + - ./ci/test-documentation.sh diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 00000000000000..cbeebdab7a5e2c --- /dev/null +++ b/.gitmodules @@ -0,0 +1,4 @@ +[submodule "sha1collisiondetection"] + path = sha1collisiondetection + url = https://github.com/cr-marcstevens/sha1collisiondetection.git + branch = master diff --git a/.mailmap b/.mailmap index 8aefb5a45218b2..96c2740fbb403d 100644 --- a/.mailmap +++ b/.mailmap @@ -13,31 +13,43 @@ Alex Riesen Alex Riesen Alex Vandiver Alexander Gavrilov +Alexander Kuleshov Alexey Shumkin Alexey Shumkin Anders Kaseorg Anders Kaseorg +Andrey Mazo Mazo, Andrey Aneesh Kumar K.V Amos Waterland Amos Waterland +Ben Peart +Ben Peart Ben Walton Benoit Sigoure Bernt Hansen Brandon Casey -brian m. carlson Brian M. Carlson -brian m. carlson +Brandon Williams +brian m. carlson +brian m. carlson +brian m. carlson Bryan Larsen Bryan Larsen Cheng Renquan Chris Shoemaker Chris Wright +Christian Ludwig Cord Seele +Christian Couder Christian Stimming +Christopher Díaz Riveros Christopher Diaz Riveros +Clemens Buchacher +Clemens Buchacher Csaba Henk Dan Johnson Dana L. How Dana L. How Dana How Daniel Barkalow +Daniel Knittl-Frank knittl Daniel Trstenjak Daniel Trstenjak David Brown @@ -45,13 +57,22 @@ David D. Kilzer David Kågedal David Reiss David S. Miller +David Turner +David Turner +Derrick Stolee +Derrick Stolee Derrick Stolee via GitGitGadget +Derrick Stolee Deskin Miller +Đoàn Trần Công Danh Doan Tran Cong Danh Dirk Süsserott +Emily Shaffer Eric Blake Eric Hanchrow Eric S. Raymond +Eric Wong Erik Faye-Lund Eyvind Bernhardsen +Fangyi Zhou Zhou Fangyi Florian Achleitner Franck Bui-Huu Frank Lichtenheld @@ -59,6 +80,7 @@ Frank Lichtenheld Fredrik Kuivinen Frédéric Heitzmann Garry Dolley +Glen Choo Greg Price Greg Price Heiko Voigt @@ -81,6 +103,8 @@ Jason McMullan Jason Riedy Jason Riedy Jay Soffian +Jean-Noël Avila Jean-Noel Avila +Jean-Noël Avila Jean-Noël AVILA Jeff King Jeff Muizelaar Jens Axboe @@ -88,7 +112,9 @@ Jens Axboe Jens Lindström Jens Lindstrom Jim Meyering Joachim Berdal Haga +Joachim Jablon Johannes Schindelin +Johannes Schindelin Johannes Schindelin via GitGitGadget Johannes Sixt Johannes Sixt Johannes Sixt @@ -108,6 +134,7 @@ Junio C Hamano Junio C Hamano Junio C Hamano Junio C Hamano +Kaartic Sivaraam Karl Wiberg Karl Hasselström Karl Wiberg Karsten Blees @@ -125,6 +152,7 @@ Lars Doelle Lars Doelle Lars Noschinski Li Hong +Linus Arver Linus Torvalds Linus Torvalds Linus Torvalds @@ -139,14 +167,19 @@ Mark Levedahl Mark Rada Martin Langhoff Martin von Zweigbergk +Masaya Suzuki +Matheus Tavares Matt Draisey Matt Kraai Matt McCutchen Matthias Kestenholz +Matthias Rüster Matthias Ruester Matthias Urlichs Matthias Urlichs +Matthieu Moy Michael Coleman -Michael J Gruber +Michael J Gruber +Michael J Gruber Michael S. Tsirkin Michael S. Tsirkin Michael S. Tsirkin @@ -167,11 +200,16 @@ Nick Stokoe Nick Woolley Nick Stokoe Nick Woolley Nicolas Morey-Chaisemartin Nicolas Morey-Chaisemartin +Nicolas Morey-Chaisemartin +Nicolas Morey-Chaisemartin +Nicolas Morey-Chaisemartin Nicolas Sebrecht +Orgad Shaneh Paolo Bonzini Pascal Obry Pascal Obry Pat Notz +Patrick Steinhardt Paul Mackerras Paul Mackerras Peter Baumann @@ -182,11 +220,17 @@ Petr Baudis Petr Baudis Phil Hord Philip Jägenstedt +Philip Oakley # secondary Philipp A. Hartmann Philippe Bruhat Ralf Thielow -Ramsay Allan Jones +Ramsay Jones +Ramkumar Ramachandra +Randall S. Becker René Scharfe +René Scharfe Rene Scharfe +Richard Hansen +Richard Hansen Robert Fitzsimons Robert Shearman Robert Zeh @@ -202,14 +246,18 @@ Sean Estabrooks Sebastian Schuberth Seth Falcon Shawn O. Pearce +Wei Shuyu Shuyu Wei +Sidhant Sharma Sidhant Sharma [:tk] Simon Hausmann Simon Hausmann Stefan Beller +Stefan Beller Stefan Naewe Stefan Naewe Stefan Sperling Štěpán Němec Stephen Boyd +Stephen P. Smith Steven Drake Steven Grimm Steven Grimm koreth@midwinter.com @@ -217,6 +265,8 @@ Steven Walter Steven Walter Sven Verdoolaege Sven Verdoolaege +SZEDER Gábor +Tao Qingyun <845767657@qq.com> Tay Ray Chuan Ted Percival Theodore Ts'o @@ -240,12 +290,14 @@ Uwe Kleine-König Uwe Kleine-König Ville Skyttä -Vitaly "_Vi" Shukela +Vitaly "_Vi" Shukela +Vitaly "_Vi" Shukela Vitaly _Vi Shukela W. Trevor King William Pursell YONETANI Tomokazu YONETANI Tomokazu YOSHIFUJI Hideaki +Yi-Jyun Pan # the two anonymous contributors are different persons: anonymous anonymous diff --git a/.tsan-suppressions b/.tsan-suppressions new file mode 100644 index 00000000000000..5ba86d68459e61 --- /dev/null +++ b/.tsan-suppressions @@ -0,0 +1,16 @@ +# Suppressions for ThreadSanitizer (tsan). +# +# This file is used by setting the environment variable TSAN_OPTIONS to, e.g., +# "suppressions=$(pwd)/.tsan-suppressions". Observe that relative paths such as +# ".tsan-suppressions" might not work. + +# A static variable is written to racily, but we always write the same value, so +# in practice it (hopefully!) doesn't matter. +race:^want_color$ +race:^transfer_debug$ + +# A boolean value, which tells whether the replace_map has been initialized or +# not, is read racily with an update. As this variable is written to only once, +# and it's OK if the value change right after reading it, this shouldn't be a +# problem. +race:^lookup_replace_object$ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 00000000000000..9225b99a28be13 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,130 @@ +# Architecture of Git for Windows + +Git for Windows is a complex project. + +## What _is_ Git for Windows? + +### A fork of `git/git` + +First and foremost, it is a friendly fork of [`git/git`](https://github.com/git/git), aiming to improve Git's Windows support. The [`git-for-windows/git`](https://github.com/git-for-windows/git) repository contains dozens of topics on top of `git/git`, some awaiting to be "upstreamed" (i.e. to be contributed to `git/git`), some still being stabilized, and a few topics are specific to the Git for Windows project and are not intended to be integrated into `git/git` at all. + +### Enhancing and maintaining Git's support for Windows + +On the source code side, Git's Windows support is made a bit more tricky than strictly necessary by the fact that Git does not have any platform abstraction layer (unlike other version control systems, such as Subversion). It relies on the presence of POSIX features such as the `hstrerror()` function, and on platforms lacking that functionality, Git provides shims. That leads to some challenges e.g. with the `stat()` function which is very slow on Windows because it has to collect much more metadata than what e.g. the very quick `GetFileAttributesExW()` Win32 API function provides, even when Git calls `stat()` merely to test for the presence of a file (for which all that gathered metadata is totally irrelevant). + +### Providing more than just source code + +In contrast to the Git project, Git for Windows not only publishes tagged source code versions, but full builds of Git. In fact, Git for Windows' primary purpose, as far as most users are concerned, is to provide a convenient installer that end-users can run to have Git on their computer, without ever having to check out `git-for-windows/git` let alone build it. In essence, Git for Windows has to maintain a separate project altogether in addition to the fork of `git/git`, just to build these release artifacts: [`git-for-windows/build-extra`](https://github.com/git-for-windows/build-extra). This repository also contains the definition for a couple of other release artifacts published by Git for Windows, e.g. the "portable" edition of Git for Windows which is a self-extracting 7-Zip archive that does not need to be installed. + +### A software distribution, really + +Another aspect that contributes to the complexity of Git for Windows is that it is not just building `git.exe` and distributes that. Due to its heritage within the Linux project, Git takes certain things for granted, such as the presence of a Unix shell, or for that matter, a package management system from which dependencies can be fetched and updated independently of Git itself. Things that are distinctly not present in most Windows setups. To accommodate for that, Git for Windows originally relied on the MSys project, a minimal fork of Cygwin providing a Unix shell ("Bash"), a Perl interpreter and similar Unix-like tools, and on the MINGW project, a project to build libraries and executables using a GNU C Compiler that relies only on Win32 API functions. As of Git for Windows v2.x, the project has switched away from [MSys](https://sourceforge.net/projects/mingw/files/MSYS/)/[MinGW](https://osdn.net/projects/mingw/) (due to less-than-active maintenance) to [the MSYS2 project](https://msys2.org). That switch brought along the benefit of a robust package management system based on [Pacman](https://archlinux.org/pacman/) (hailing from Arch Linux). To support Windows users, who are in general unfamiliar with Linux-like package management and the need to update installed packages frequently, Git for Windows bundles a subset of its own fork of MSYS2. To put things in perspective: Git for Windows bundles files from ~170 packages, one of which contains Git, and another one contains Git's help files. In that respect, Git for Windows acts like a distribution more than like a mere single software application. + +Most of MSYS2's packages that are bundled in Git for Windows are consumed directly from MSYS2. Others need forks that are maintained by Git for Windows project, to support Git for Windows better. These forks live in the [`git-for-windows/MSYS2-packages`](https://github.com/git-for-windows/MSYS2-packages) and [`git-for-windows/MINGW-packages`](https://github.com/git-for-windows/MINGW-packages) repositories. There are several reasons justifying these forks. For example, the Git for Windows' flavor of the MSYS2 runtime behaves like Git's test suite expects it while MSYS2's flavor does not. Another example: The Bash executable bundled in Git for Windows is code-signed with the same certificate as `git.exe` to help anti-malware programs get out of the users' way. That is why Git for Windows maintains its own `bash` Pacman package. And since MSYS2 dropped 32-bit support already, Git for Windows has to update the 32-bit Pacman packages itself, which is done in the git-for-windows/MSYS2-packages repository. (Side note: the 32-bit issue is a bit more complicated, actually: MSYS2 _still_ builds _MINGW_ packages targeting i686 processors, but no longer any _MSYS_ packages for said processor architecture, and Git for Windows does not keep all of the 32-bit MSYS packages up to date but instead judiciously decides which packages are vital enough as far as Git is concerned to justify the maintenance cost.) + +### Supporting third-party applications that use Git's functionality + +Since the infrastructure required by Git is non-trivial the installer (or for that matter, the Portable Git) is not exactly light-weight: As of January 2023, both artifacts are over fifty megabytes. This is a problem for third-party applications wishing to bundle a version of Git for Windows, which is often advisable given that applications may depend on features that have been introduced only in recent Git versions and therefore relying on an installed Git for Windows could break things. To help with that, the Git for Windows project also provides MinGit as a release artifact, a zip file that is much smaller than the full installer and that contains only the parts of Git for Windows relevant for third-party applications. It lacks Git GUI, for example, as well as the terminal program MinTTY, or for that matter, the documentation. + +### Supporting `git/git`'s GitHub workflows + +The Git for Windows project is also responsible for keeping the Windows part of `git/git`'s automated builds up and running. On Windows, there is no canonical and easy way to get a build environment necessary to build Git and run its test suite, therefore this is a non-trivial task that comes with its own maintenance cost. Git for Windows provides two GitHub Actions to help with that: [`git-for-windows/setup-git-for-windows-sdk`](https://github.com/git-for-windows/setup-git-for-windows-sdk) to set up a tiny subset of Git for Windows' full SDK (which would require about 500MB to be cloned, as opposed to the ~75MB of that subset) and [`git-for-windows/get-azure-pipelines-artifact`](https://github.com/git-for-windows/get-azure-pipelines-artifact) e.g. to download some regularly pre-built artifacts (for example, when `git/git`'s automated tests ran on an Ubuntu version that did not provide an up to date [Coccinelle](https://coccinelle.gitlabpages.inria.fr/website/) package, this GitHub Action was used to download a pre-built version of that Debian package). + +## Maintaining Git for Windows' components + +Git for Windows uses a combination of [a GitHub App called GitForWindowsHelper](https://github.com/git-for-windows/gfw-helper-github-app) (to listen for so-called [slash commands](https://github.com/git-for-windows/gfw-helper-github-app#slash-commands)) combined with workflows in [the `git-for-windows-automation` repository](https://github.com/git-for-windows/git-for-windows-automation/) (for computationally heavy tasks) to support Git for Windows' repetitive tasks. + +This heavy automation serves two purposes: + +1. Document the knowledge about "how things are done" in the Git for Windows project. +2. Make Git for Windows' maintenance less tedious by off-loading as many tasks onto machines as possible. + +One neat trick of some `git-for-windows-automation` workflows is that they "mirror back" check runs to the targeted PRs in another repository. This essentially allows versioning the source code independently of the workflow definition. + +Here is a diagram showing how the bits and pieces fit together. + +```mermaid +graph LR + A[`monitor-components`] --> |opens| B + B{issues labeled
`component-update`} --> |/open pr| C + C((GitForWindowsHelper)) --> |triggers| D + D[`open-pr`] --> |opens| E + E{PR in
MINGW-packages
MSYS2-packages
build-extra} --> |closes| B + E --> |/deploy| F + F((GitForWindowsHelper)) --> |triggers| G + G[`build-and-deploy`] --> |deploys to| H + H{Pacman repository} + C --> |backed by| I + F --> |backed by| I + I[[Azure Function]] + D --> |running in| J + G --> | running in| J + J[[git-for-windows-automation]] + K[[git-sdk-32
git-sdk-64
git-sdk-arm64]] --> |syncing from| H + B --> |/add release note| L + L[`add-release-note`] +``` + +For the curious mind, here are [detailed instructions how the Azure Function backing the GitForWindowsHelper GitHub App was set up](https://github.com/git-for-windows/gfw-helper-github-app#how-this-github-app-was-set-up). + +### The `monitor-components` workflow + +When new versions of components that Git for Windows builds become available, new Pacman packages have to be built. To this end, [the `monitor-components` workflow](https://github.com/git-for-windows/git/blob/main/.github/workflows/monitor-components.yml) monitors a couple of RSS feeds and opens new tickets labeled `component-update` for such new versions. + +### Opening Pull Requests to update Git for Windows' components + +After determining that such a ticket indeed indicates the need for a new Pacman package build, a Git for Windows maintainer issues the `/open pr` command via an issue comment ([example](https://github.com/git-for-windows/git/issues/4281#issuecomment-1426859787)), which gets picked up by the GitForWindowsHelper GitHub App, which in turn triggers [the `open-pr` workflow](https://github.com/git-for-windows/git-for-windows-automation/blob/main/.github/workflows/open-pr.yml) in the `git-for-windows-automation` repository. + +### Deploying the Pacman packages + +This will open a Pull Request in one of Git for Windows' repositories, and once the PR build passes, a Git for Windows maintainer issues the `/deploy` command ([example](https://github.com/git-for-windows/MINGW-packages/pull/69#issuecomment-1427591890)), which gets picked up by the GitForWindowsHelper GitHub App, which triggers [the `build-and-deploy` workflow](https://github.com/git-for-windows/git-for-windows-automation/blob/main/.github/workflows/build-and-deploy.yml). + +### Adding release notes + +Finally, once the packages have been built and deployed to the Pacman repository (which is hosted in Azure Blob Storage), a Git for Windows maintainer will merge the PR(s), which in turn will close the ticket, and the maintainer then issues an `/add release note` command ([example](https://github.com/git-for-windows/MINGW-packages/pull/69#issuecomment-1427782230)), which again gets picked up by the GitForWindowsHelper GitHub App that triggers [the `add-release-note` workflow](https://github.com/git-for-windows/build-extra/blob/main/.github/workflows/add-release-note.yml) that creates and pushes a new commit to the `ReleaseNotes.md` file in `build-extra` ([example](https://github.com/git-for-windows/build-extra/commit/b39c148ff8dc0e987afdb677d17c46a8e99fd0ef)). + +## Releasing official Git for Windows versions + +A relatively infrequent part of Git for Windows' maintainers' duties, if the most rewarding part, is the task of releasing new versions of Git for Windows. + +Most commonly, this is done in response to the "upstream" Git project releasing a new version. When that happens, a Git for Windows maintainer runs [the helper script](https://github.com/git-for-windows/build-extra/blob/main/shears.sh) to perform a "merging rebase" (i.e. a rebase that starts with a fake-merge of the previous tip commit, to maintain both a clean set of commits as well as a [fast-forwarding](https://git-scm.com/docs/git-merge#Documentation/git-merge.txt---ff-only) commit history). + +Once that is done, the maintainer will open a Pull Request to benefit from the automated builds and tests ([example](https://github.com/git-for-windows/git/pull/4160)) as well as from reviews of the [`range-diff`](https://git-scm.com/docs/git-range-diff) relative to the current `main` branch. + +Once everything looks good, the maintainer will issue the `/git-artifacts` command ([example](https://github.com/git-for-windows/git/pull/4160#issuecomment-1346801735)). This will trigger an automated workflow that builds all of the release artifacts: installers, Portable Git, MinGit, `.tar.xz` archive and a NuGet package. Apart from the NuGet package, two sets of artifacts are built: targeting 32-bit ("x86") and 64-bit ("amd64"). + +Once these artifacts are built, the maintainer will download the installer and run [the "pre-flight checklist"](https://github.com/git-for-windows/build-extra/blob/main/installer/checklist.txt). + +If everything looks good, a `/release` command will be issued, which triggers yet another workflow that will download the just-built-and-verified release artifacts, publish them as a new GitHub release, publish the NuGet packages, deploy the Pacman packages to the Pacman repository, send out an announcement mail, and update the respective repositories including [Git for Windows' website](https://gitforwindows.org/). + +As mentioned [before](#architecture-of-git-for-windows), the `/git-artifacts` and `/release` commands are picked up by the GitForWindowsHelper GitHub App which subsequently triggers the respective workflows in the `git-for-windows-automation` repository. Here is a diagram: + +```mermaid +graph LR + A{Pull Request
updating to
new Git version} --> |/git-artifacts| B + B((GitForWindowsHelper)) --> |triggers| C + C[`tag-git`] --> |upon successful build
triggers| D + D((GitForWindowsHelper)) --> |triggers| E + E[`git-artifacts`] + E --> |maintainer verifies artifacts| E + A --> |upon verified `git-artifacts`
/release| F + F[`release-git`] + C --> |running in| J + E --> | running in| J + F --> | running in| J + J[[git-for-windows-automation]] +``` + +## Managing Windows/ARM64 builds + +The GitForWindowsHelper comes in real handy for Git for Windows' Pacman packages for the `aarch64` architecture, i.e. for Windows/ARM64. These packages cannot be built in regular hosted GitHub Actions runners because there are none of that architecture. To help with that, the respective workflows in `git-for-windows-automation` use the label `runs-on: ["Windows", "ARM64"]` to indicate that they need a self-hosted Windows/ARM64 runner. + +It would not be cost-effective to have a VM running permanently, hosting such a self-hosted runner: Git for Windows does not build such packages often enough (usually once or twice per week is more the norm). + +Therefore, VMs providing self-hosted GitHub Actions runners are spun up and torn down as needed. This job is done by the GitForWindowsHelper: + +- When a job is queued asking for above-mentioned labels, [the `create-self-hosted-runner` workflow](https://github.com/git-for-windows/git-for-windows-automation/blob/09ec165f44a0a3d84d8f0e26a4939667b4522635/.github/workflows/create-azure-self-hosted-runners.yml) is started. This deploys an Azure Resource Management template that creates an ephemeral self-hosted runner (i.e. a runner that will pick up one job and then is immediately unregistered). + +- When a job with above-mentioned labels has finished, the GitForWindowsHelper triggers [the `delete-self-hosted-runner` workflow](https://github.com/git-for-windows/git-for-windows-automation/blob/09ec165f44a0a3d84d8f0e26a4939667b4522635/.github/workflows/delete-self-hosted-runner.yml) that tears down the now no longer used VM. + +The GitForWindowsHelper GitHub App will also detect when a job is queued for a PR from a forked repository. This is considered unauthorized use, and the job will be canceled immediately by the GitHub App instead of spinning up a self-hosted runner for it. \ No newline at end of file diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000000000..4daef7e3ce9196 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,139 @@ +# Git for Windows Code of Conduct + +This code of conduct outlines our expectations for participants within +the **Git for Windows** community, as well as steps for reporting unacceptable +behavior. We are committed to providing a welcoming and inspiring community +for all and expect our code of conduct to be honored. Anyone who violates +this code of conduct may be banned from the community. + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official email address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the Git for Windows maintainer. + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000000000..ca9770df8c4808 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,417 @@ +How to Contribute to Git for Windows +==================================== + +Git was originally designed for Unix systems and still today, all the build tools for the Git +codebase assume you have standard Unix tools available in your path. If you have an open-source +mindset and want to start contributing to Git, but primarily use a Windows machine, then you may +have trouble getting started. This guide is for you. + +Get the Source +-------------- + +Clone the [GitForWindows repository on GitHub](https://github.com/git-for-windows/git). +It is helpful to create your own fork for storing your development branches. + +Windows uses different line endings than Unix systems. See +[this GitHub article on working with line endings](https://help.github.com/articles/dealing-with-line-endings/#refreshing-a-repository-after-changing-line-endings) +if you have trouble with line endings. + +Build the Source +---------------- + +First, download and install the latest [Git for Windows SDK (64-bit)](https://github.com/git-for-windows/build-extra/releases/latest). +When complete, you can run the Git SDK, which creates a new Git Bash terminal window with +the additional development commands, such as `make`. + + As of time of writing, the SDK uses a different credential manager, so you may still want to use normal Git + Bash for interacting with your remotes. Alternatively, use SSH rather than HTTPS and + avoid credential manager problems. + +You should now be ready to type `make` from the root of your `git` source directory. +Here are some helpful variations: + +* `make -j[N] DEVELOPER=1`: Compile new sources using up to N concurrent processes. + The `DEVELOPER` flag turns on all warnings; code failing these warnings will not be + accepted upstream ("upstream" = "the core Git project"). +* `make clean`: Delete all compiled files. + +When running `make`, you can use `-j$(nproc)` to automatically use the number of processors +on your machine as the number of concurrent build processes. + +You can go deeper on the Windows-specific build process by reading the +[technical overview](https://github.com/git-for-windows/git/wiki/Technical-overview) or the +[guide to compiling Git with Visual Studio](https://github.com/git-for-windows/git/wiki/Compiling-Git-with-Visual-Studio). + +## Building `git` on Windows with Visual Studio + +The typical approach to building `git` is to use the standard `Makefile` with GCC, as +above. Developers working in a Windows environment may want to instead build with the +[Microsoft Visual C++ compiler and libraries toolset (MSVC)](https://blogs.msdn.microsoft.com/vcblog/2017/03/07/msvc-the-best-choice-for-windows/). +There are a few benefits to using MSVC over GCC during your development, including creating +symbols for debugging and [performance tracing](https://github.com/Microsoft/perfview#perfview-overview). + +There are two ways to build Git for Windows using MSVC. Each have their own merits. + +### Using SDK Command Line + +Use one of the following commands from the SDK Bash window to build Git for Windows: + +``` + make MSVC=1 -j12 + make MSVC=1 DEBUG=1 -j12 +``` + +The first form produces release-mode binaries; the second produces debug-mode binaries. +Both forms produce PDB files and can be debugged. However, the first is best for perf +tracing and the second is best for single-stepping. + +You can then open Visual Studio and select File -> Open -> Project/Solution and select +the compiled `git.exe` file. This creates a basic solution and you can use the debugging +and performance tracing tools in Visual Studio to monitor a Git process. Use the Debug +Properties page to set the working directory and command line arguments. + +Be sure to clean up before switching back to GCC (or to switch between debug and +release MSVC builds): + +``` + make MSVC=1 -j12 clean + make MSVC=1 DEBUG=1 -j12 clean +``` + +### Using the IDE + +If you prefer working in Visual Studio with a solution full of projects, then you can use +CMake, either by letting Visual Studio configure it automatically (simply open Git's +top-level directory via `File>Open>Folder...`) or by (downloading and) running +[CMake](https://cmake.org) manually. + +What to Change? +--------------- + +Many new contributors ask: What should I start working on? + +One way to win big with the open-source community is to look at the +[issues page](https://github.com/git-for-windows/git/issues) and see if there are any issues that +you can fix quickly, or if anything catches your eye. + +You can also look at [the unofficial Chromium issues page](https://crbug.com/git) for +multi-platform issues. You can look at recent user questions on +[the Git mailing list](https://public-inbox.org/git). + +Or you can "scratch your own itch", i.e. address an issue you have with Git. The team at Microsoft where the Git for Windows maintainer works, for example, is focused almost entirely on [improving performance](https://blogs.msdn.microsoft.com/devops/2018/01/11/microsofts-performance-contributions-to-git-in-2017/). +We approach our work by finding something that is slow and try to speed it up. We start our +investigation by reliably reproducing the slow behavior, then running that example using +the MSVC build and tracing the results in PerfView. + +You could also think of something you wish Git could do, and make it do that thing! The +only concern I would have with this approach is whether or not that feature is something +the community also wants. If this excites you though, go for it! Don't be afraid to +[get involved in the mailing list](http://vger.kernel.org/vger-lists.html#git) early for +feedback on the idea. + +Test Your Changes +----------------- + +After you make your changes, it is important that you test your changes. Manual testing is +important, but checking and extending the existing test suite is even more important. You +want to run the functional tests to see if you broke something else during your change, and +you want to extend the functional tests to be sure no one breaks your feature in the future. + +### Functional Tests + +Navigate to the `t/` directory and type `make` to run all tests or use `prove` as +[described in the Git for Windows wiki](https://github.com/git-for-windows/git/wiki/Building-Git): + +``` +prove -j12 --state=failed,save ./t[0-9]*.sh +``` + +You can also run each test directly by running the corresponding shell script with a name +like `tNNNN-descriptor.sh`. + +If you are adding new functionality, you may need to create unit tests by creating +helper commands that test a very limited action. These commands are stored in `t/helpers`. +When adding a helper, be sure to add a line to `t/Makefile` and to the `.gitignore` for the +binary file you add. The Git community prefers functional tests using the full `git` +executable, so try to exercise your new code using `git` commands before creating a test +helper. + +To find out why a test failed, repeat the test with the `-x -v -d -i` options and then +navigate to the appropriate "trash" directory to see the data shape that was used for the +test failed step. + +Read [`t/README`](t/README) for more details. + +### Performance Tests + +If you are working on improving performance, you will need to be acquainted with the +performance tests in `t/perf`. There are not too many performance tests yet, but adding one +as your first commit in a patch series helps to communicate the boost your change provides. + +To check the change in performance across multiple versions of `git`, you can use the +`t/perf/run` script. For example, to compare the performance of `git rev-list` across the +`core/master` and `core/next` branches compared to a `topic` branch, you can run + +``` +cd t/perf +./run core/master core/next topic -- p0001-rev-list.sh +``` + +You can also set certain environment variables to help test the performance on different +repositories or with more repetitions. The full list is available in +[the `t/perf/README` file](t/perf/README), +but here are a few important ones: + +``` +GIT_PERF_REPO=/path/to/repo +GIT_PERF_LARGE_REPO=/path/to/large/repo +GIT_PERF_REPEAT_COUNT=10 +``` + +When running the performance tests on Linux, you may see a message "Can't locate JSON.pm in +@INC" and that means you need to run `sudo cpanm install JSON` to get the JSON perl package. + +For running performance tests, it can be helpful to set up a few repositories with strange +data shapes, such as: + +**Many objects:** Clone repos such as [Kotlin](https://github.com/jetbrains/kotlin), [Linux](https://github.com/torvalds/linux), or [Android](https://source.android.com/setup/downloading). + +**Many pack-files:** You can split a fresh clone into multiple pack-files of size at most +16MB by running `git repack -adfF --max-pack-size=16m`. See the +[`git repack` documentation](https://git-scm.com/docs/git-repack) for more information. +You can count the number of pack-files using `ls .git/objects/pack/*.pack | wc -l`. + +**Many loose objects:** If you already split your repository into multiple pack-files, then +you can pick one to split into loose objects using `cat .git/objects/pack/[id].pack | git unpack-objects`; +delete the `[id].pack` and `[id].idx` files after this. You can count the number of loose +bjects using `ls .git/objects/??/* | wc -l`. + +**Deep history:** Usually large repositories also have deep histories, but you can use the +[test-many-commits-1m repo](https://github.com/cirosantilli/test-many-commits-1m/) to +target deep histories without the overhead of many objects. One issue with this repository: +there are no merge commits, so you will need to use a different repository to test a "wide" +commit history. + +**Large Index:** You can generate a large index and repo by using the scripts in +`t/perf/repos`. There are two scripts. `many-files.sh` which will generate a repo with +same tree and blobs but different paths. Using `many-files.sh -d 5 -w 10 -f 9` will create +a repo with ~1 million entries in the index. `inflate-repo.sh` will use an existing repo +and copy the current work tree until it is a specified size. + +Test Your Changes on Linux +-------------------------- + +It can be important to work directly on the [core Git codebase](https://github.com/git/git), +such as a recent commit into the `master` or `next` branch that has not been incorporated +into Git for Windows. Also, it can help to run functional and performance tests on your +code in Linux before submitting patches to the mailing list, which focuses on many platforms. +The differences between Windows and Linux are usually enough to catch most cross-platform +issues. + +### Using the Windows Subsystem for Linux + +The [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install-win10) +allows you to [install Ubuntu Linux as an app](https://www.microsoft.com/en-us/store/p/ubuntu/9nblggh4msv6) +that can run Linux executables on top of the Windows kernel. Internally, +Linux syscalls are interpreted by the WSL, everything else is plain Ubuntu. + +First, open WSL (either type "Bash" in Cortana, or execute "bash.exe" in a CMD window). +Then install the prerequisites, and `git` for the initial clone: + +``` +sudo apt-get update +sudo apt-get install git gcc make libssl-dev libcurl4-openssl-dev \ + libexpat-dev tcl tk gettext git-email zlib1g-dev +``` + +Then, clone and build: + +``` +git clone https://github.com/git-for-windows/git +cd git +git remote add -f upstream https://github.com/git/git +make +``` + +Be sure to clone into `/home/[user]/` and not into any folder under `/mnt/?/` or your build +will fail due to colons in file names. + +### Using a Linux Virtual Machine with Hyper-V + +If you prefer, you can use a virtual machine (VM) to run Linux and test your changes in the +full environment. The test suite runs a lot faster on Linux than on Windows or with the WSL. +You can connect to the VM using an SSH terminal like +[PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/). + +The following instructions are for using Hyper-V, which is available in some versions of Windows. +There are many virtual machine alternatives available, if you do not have such a version installed. + +* [Download an Ubuntu Server ISO](https://www.ubuntu.com/download/server). +* Open [Hyper-V Manager](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v). +* [Set up a virtual switch](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/connect-to-network) + so your VM can reach the network. +* Select "Quick Create", name your machine, select the ISO as installation source, and un-check + "This virtual machine will run Windows." +* Go through the Ubuntu install process, being sure to select to install OpenSSH Server. +* When install is complete, log in and check the SSH server status with `sudo service ssh status`. + * If the service is not found, install with `sudo apt-get install openssh-server`. + * If the service is not running, then use `sudo service ssh start`. +* Use `shutdown -h now` to shutdown the VM, go to the Hyper-V settings for the VM, expand Network Adapter + to select "Advanced Features", and set the MAC address to be static (this can save your VM from losing + network if shut down incorrectly). +* Provide as many cores to your VM as you can (for parallel builds). +* Restart your VM, but do not connect. +* Use `ssh` in Git Bash, download [PuTTY](http://www.putty.org/), or use your favorite SSH client to connect to the VM through SSH. + +In order to build and use `git`, you will need the following libraries via `apt-get`: + +``` +sudo apt-get update +sudo apt-get install git gcc make libssl-dev libcurl4-openssl-dev \ + libexpat-dev tcl tk gettext git-email zlib1g-dev +``` + +To get your code from your Windows machine to the Linux VM, it is easiest to push the branch to your fork of Git and clone your fork in the Linux VM. + +Don't forget to set your `git` config with your preferred name, email, and editor. + +Polish Your Commits +------------------- + +Before submitting your patch, be sure to read the [coding guidelines](https://github.com/git/git/blob/master/Documentation/CodingGuidelines) +and check your code to match as best you can. This can be a lot of effort, but it saves +time during review to avoid style issues. + +The other possibly major difference between the mailing list submissions and GitHub PR workflows +is that each commit will be reviewed independently. Even if you are submitting a +patch series with multiple commits, each commit must stand on it's own and be reviewable +by itself. Make sure the commit message clearly explain the why of the commit not the how. +Describe what is wrong with the current code and how your changes have made the code better. + +When preparing your patch, it is important to put yourself in the shoes of the Git community. +Accepting a patch requires more justification than approving a pull request from someone on +your team. The community has a stable product and is responsible for keeping it stable. If +you introduce a bug, then they cannot count on you being around to fix it. When you decided +to start work on a new feature, they were not part of the design discussion and may not +even believe the feature is worth introducing. + +Questions to answer in your patch message (and commit messages) may include: +* Why is this patch necessary? +* How does the current behavior cause pain for users? +* What kinds of repositories are necessary for noticing a difference? +* What design options did you consider before writing this version? Do you have links to + code for those alternate designs? +* Is this a performance fix? Provide clear performance numbers for various well-known repos. + +Here are some other tips that we use when cleaning up our commits: + +* Commit messages should be wrapped at 76 columns per line (or less; 72 is also a + common choice). +* Make sure the commits are signed off using `git commit (-s|--signoff)`. See + [SubmittingPatches](https://github.com/git/git/blob/v2.8.1/Documentation/SubmittingPatches#L234-L286) + for more details about what this sign-off means. +* Check for whitespace errors using `git diff --check [base]...HEAD` or `git log --check`. +* Run `git rebase --whitespace=fix` to correct upstream issues with whitespace. +* Become familiar with interactive rebase (`git rebase -i`) because you will be reordering, + squashing, and editing commits as your patch or series of patches is reviewed. +* Make sure any shell scripts that you add have the executable bit set on them. This is + usually for test files that you add in the `/t` directory. You can use + `git add --chmod=+x [file]` to update it. You can test whether a file is marked as executable + using `git ls-files --stage \*.sh`; the first number is 100755 for executable files. +* Your commit titles should match the "area: change description" format. Rules of thumb: + * Choose ": " prefix appropriately. + * Keep the description short and to the point. + * The word that follows the ": " prefix is not capitalized. + * Do not include a full-stop at the end of the title. + * Read a few commit messages -- using `git log origin/master`, for instance -- to + become acquainted with the preferred commit message style. +* Build source using `make DEVELOPER=1` for extra-strict compiler warnings. + +Submit Your Patch +----------------- + +Git for Windows [accepts pull requests on GitHub](https://github.com/git-for-windows/git/pulls), but +these are reserved for Windows-specific improvements. For core Git, submissions are accepted on +[the Git mailing list](https://public-inbox.org/git). + +### Configure Git to Send Emails + +There are a bunch of options for configuring the `git send-email` command. These options can +be found in the documentation for +[`git config`](https://git-scm.com/docs/git-config) and +[`git send-email`](https://git-scm.com/docs/git-send-email). + +``` +git config --global sendemail.smtpserver +git config --global sendemail.smtpserverport 587 +git config --global sendemail.smtpencryption tls +git config --global sendemail.smtpuser +``` + +To avoid storing your password in the config file, store it in the Git credential manager: + +``` +$ git credential fill +protocol=smtp +host= +username= +password=password +``` + +Before submitting a patch, read the [Git documentation on submitting patches](https://github.com/git/git/blob/master/Documentation/SubmittingPatches). + +To construct a patch set, use the `git format-patch` command. There are three important options: + +* `--cover-letter`: If specified, create a `[v#-]0000-cover-letter.patch` file that can be + edited to describe the patch as a whole. If you previously added a branch description using + `git branch --edit-description`, you will end up with a 0/N mail with that description and + a nice overall diffstat. +* `--in-reply-to=[Message-ID]`: This will mark your cover letter as replying to the given + message (which should correspond to your previous iteration). To determine the correct Message-ID, + find the message you are replying to on [public-inbox.org/git](https://public-inbox.org/git) and take + the ID from between the angle brackets. + +* `--subject-prefix=[prefix]`: This defaults to [PATCH]. For subsequent iterations, you will want to + override it like `--subject-prefix="[PATCH v2]"`. You can also use the `-v` option to have it + automatically generate the version number in the patches. + +If you have multiple commits and use the `--cover-letter` option be sure to open the +`0000-cover-letter.patch` file to update the subject and add some details about the overall purpose +of the patch series. + +### Examples + +To generate a single commit patch file: +``` +git format-patch -s -o [dir] -1 +``` +To generate four patch files from the last three commits with a cover letter: +``` +git format-patch --cover-letter -s -o [dir] HEAD~4 +``` +To generate version 3 with four patch files from the last four commits with a cover letter: +``` +git format-patch --cover-letter -s -o [dir] -v 3 HEAD~4 +``` + +### Submit the Patch + +Run [`git send-email`](https://git-scm.com/docs/git-send-email), starting with a test email: + +``` +git send-email --to=yourself@address.com [dir with patches]/*.patch +``` + +After checking the receipt of your test email, you can send to the list and to any +potentially interested reviewers. + +``` +git send-email --to=git@vger.kernel.org --cc= --cc= [dir with patches]/*.patch +``` + +To submit a nth version patch (say version 3): + +``` +git send-email --to=git@vger.kernel.org --cc= --cc= \ + --in-reply-to= [dir with patches]/*.patch +``` diff --git a/Documentation/.gitignore b/Documentation/.gitignore index 2c8b2d612ee0d6..9f4bb3c4bf9e9e 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -10,4 +10,11 @@ howto-index.txt doc.dep cmds-*.txt mergetools-*.txt -manpage-base-url.xsl +SubmittingPatches.txt +tmp-doc-diff/ +tmp-meson-diff/ +GIT-ASCIIDOCFLAGS +/.build/ +/GIT-EXCLUDED-PROGRAMS +/asciidoc.conf +/asciidoctor-extensions.rb diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt new file mode 100644 index 00000000000000..27acff86db4883 --- /dev/null +++ b/Documentation/BreakingChanges.txt @@ -0,0 +1,174 @@ += Upcoming breaking changes + +The Git project aims to ensure backwards compatibility to the best extent +possible. Minor releases will not break backwards compatibility unless there is +a very strong reason to do so, like for example a security vulnerability. + +Regardless of that, due to the age of the Git project, it is only natural to +accumulate a backlog of backwards-incompatible changes that will eventually be +required to keep the project aligned with a changing world. These changes fall +into several categories: + +* Changes to long established defaults. +* Concepts that have been replaced with a superior design. +* Concepts, commands, configuration or options that have been lacking in major + ways and that cannot be fixed and which will thus be removed without any + replacement. + +Explicitly not included in this list are fixes to minor bugs that may cause a +change in user-visible behavior. + +The Git project irregularly releases breaking versions that deliberately break +backwards compatibility with older versions. This is done to ensure that Git +remains relevant, safe and maintainable going forward. The release cadence of +breaking versions is typically measured in multiple years. We had the following +major breaking releases in the past: + +* Git 1.6.0, released in August 2008. +* Git 2.0, released in May 2014. + +We use . release numbers these days, starting from Git 2.0. For +future releases, our plan is to increment in the release number when we +make the next breaking release. Before Git 2.0, the release numbers were +1.. with the intention to increment for "usual" breaking +releases, reserving the jump to Git 2.0 for really large backward-compatibility +breaking changes. + +The intent of this document is to track upcoming deprecations for future +breaking releases. Furthermore, this document also tracks what will _not_ be +deprecated. This is done such that the outcome of discussions document both +when the discussion favors deprecation, but also when it rejects a deprecation. + +Items should have a clear summary of the reasons why we do or do not want to +make the described change that can be easily understood without having to read +the mailing list discussions. If there are alternatives to the changed feature, +those alternatives should be pointed out to our users. + +All items should be accompanied by references to relevant mailing list threads +where the deprecation was discussed. These references use message-IDs, which +can visited via + + https://lore.kernel.org/git/$message_id/ + +to see the message and its surrounding discussion. Such a reference is there to +make it easier for you to find how the project reached consensus on the +described item back then. + +This is a living document as the environment surrounding the project changes +over time. If circumstances change, an earlier decision to deprecate or change +something may need to be revisited from time to time. So do not take items on +this list to mean "it is settled, do not waste our time bringing it up again". + +== Procedure + +Discussing the desire to make breaking changes, declaring that breaking +changes are made at a certain version boundary, and recording these +decisions in this document, are necessary but not sufficient. +Because such changes are expected to be numerous, and the design and +implementation of them are expected to span over time, they have to +be deployable trivially at such a version boundary. + +The breaking changes MUST be guarded with the a compile-time switch, +WITH_BREAKING_CHANGES, to help this process. When built with it, +the resulting Git binary together with its documentation would +behave as if these breaking changes slated for the next big version +boundary are already in effect. We may also want to have a CI job +or two to exercise the work-in-progress version of Git with these +breaking changes. + + +== Git 3.0 + +The following subsections document upcoming breaking changes for Git 3.0. There +is no planned release date for this breaking version yet. The early +adopter configuration used for changes for this release is `feature.git3`. + +Proposed changes and removals only include items which are "ready" to be done. +In other words, this is not supposed to be a wishlist of features that should +be changed to or replaced in case the alternative was implemented already. + +=== Changes + +* The default hash function for new repositories will be changed from "sha1" + to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays + recommended against in FIPS 140-2 and similar certifications. Furthermore, + there are practical attacks on SHA-1 that weaken its cryptographic properties: ++ + ** The SHAppening (2015). The first demonstration of a practical attack + against SHA-1 with 2^57 operations. + ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations. + ** Birthday-Near-Collision (2019). This attack allows for chosen prefix + attacks with 2^68 operations. + ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63 + operations. ++ +While we have protections in place against known attacks, it is expected +that more attacks against SHA-1 will be found by future research. Paired +with the ever-growing capability of hardware, it is only a matter of time +before SHA-1 will be considered broken completely. We want to be prepared +and will thus change the default hash algorithm to "sha256" for newly +initialized repositories. ++ +An important requirement for this change is that the ecosystem is ready to +support the "sha256" object format. This includes popular Git libraries, +applications and forges. ++ +There is no plan to deprecate the "sha1" object format at this point in time. ++ +Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>, +<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>, +. + +=== Removals + +* Support for grafting commits has long been superseded by git-replace(1). + Grafts are inferior to replacement refs: ++ + ** Grafts are a local-only mechanism and cannot be shared across + repositories. + ** Grafts can lead to hard-to-diagnose problems when transferring objects + between repositories. ++ +The grafting mechanism has been marked as outdated since e650d0643b (docs: mark +info/grafts as outdated, 2014-03-05) and will be removed. ++ +Cf. <20140304174806.GA11561@sigill.intra.peff.net>. + +* The git-pack-redundant(1) command can be used to remove redundant pack files. + The subcommand is unusably slow and the reason why nobody reports it as a + performance bug is suspected to be the absence of users. We have nominated + the command for removal and have started to emit a user-visible warning in + c3b58472be (pack-redundant: gauge the usage before proposing its removal, + 2020-08-25) whenever the command is executed. ++ +So far there was a single complaint about somebody still using the command, but +that complaint did not cause us to reverse course. On the contrary, we have +doubled down on the deprecation and starting with 4406522b76 (pack-redundant: +escalate deprecation warning to an error, 2023-03-23), the command dies unless +the user passes the `--i-still-use-this` option. ++ +There have not been any subsequent complaints, so this command will finally be +removed. ++ +Cf. , + , + <20230323204047.GA9290@coredump.intra.peff.net>, + +== Superseded features that will not be deprecated + +Some features have gained newer replacements that aim to improve the design in +certain ways. The fact that there is a replacement does not automatically mean +that the old way of doing things will eventually be removed. This section tracks +those features with newer alternatives. + +* The features git-checkout(1) offers are covered by the pair of commands + git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still + widespread, and it is not expected that this will change anytime soon, all + three commands will stay. ++ +This decision may get revisited in case we ever figure out that there are +almost no users of any of the commands anymore. ++ +Cf. , +, +<112b6568912a6de6672bf5592c3a718e@manjaro.org>. diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 894546dd75416f..ba047ed224afbd 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -1,5 +1,5 @@ -Like other projects, we also have some guidelines to keep to the -code. For Git in general, three rough rules are: +Like other projects, we also have some guidelines for our code. For +Git in general, a few rough rules are: - Most importantly, we never say "It's in POSIX; we'll happily ignore your needs should your system not conform to it." @@ -24,7 +24,14 @@ code. For Git in general, three rough rules are: "Once it _is_ in the tree, it's not really worth the patch noise to go and fix it up." - Cf. http://article.gmane.org/gmane.linux.kernel/943020 + Cf. https://lore.kernel.org/all/20100126160632.3bdbe172.akpm@linux-foundation.org/ + + - Log messages to explain your changes are as important as the + changes themselves. Clearly written code and in-code comments + explain how the code works and what is assumed from the surrounding + context. The log messages explain what the changes wanted to + achieve and why the changes were necessary (more on this in the + accompanying SubmittingPatches document). Make your code readable and sensible, and don't try to be clever. @@ -33,10 +40,13 @@ As for more concrete guidelines, just imitate the existing code contributing to). It is always preferable to match the _local_ convention. New code added to Git suite is expected to match the overall style of existing code. Modifications to existing -code is expected to match the style the surrounding code already +code are expected to match the style the surrounding code already uses (even if it doesn't match the overall style of existing code). -But if you must have a list of rules, here they are. +But if you must have a list of rules, here are some language +specific ones. Note that Documentation/ToolsForGit.txt document +has a collection of tips to help you use some external tools +to conform to these guidelines. For shell scripts specifically (not exhaustive): @@ -75,7 +85,7 @@ For shell scripts specifically (not exhaustive): - If you want to find out if a command is available on the user's $PATH, you should use 'type ', instead of 'which '. - The output of 'which' is not machine parseable and its exit code + The output of 'which' is not machine parsable and its exit code is not reliable across platforms. - We use POSIX compliant parameter substitutions and avoid bashisms; @@ -91,16 +101,10 @@ For shell scripts specifically (not exhaustive): - No shell arrays. - - No strlen ${#parameter}. - - No pattern replacement ${parameter/pattern/string}. - We use Arithmetic Expansion $(( ... )). - - Inside Arithmetic Expansion, spell shell variables with $ in front - of them, as some shells do not grok $((x)) while accepting $(($x)) - just fine (e.g. dash older than 0.5.4). - - We do not use Process Substitution <(list) or >(list). - Do not write control structures on a single line with semicolon. @@ -118,6 +122,24 @@ For shell scripts specifically (not exhaustive): do this fi + - If a command sequence joined with && or || or | spans multiple + lines, put each command on a separate line and put && and || and | + operators at the end of each line, rather than the start. This + means you don't need to use \ to join lines, since the above + operators imply the sequence isn't finished. + + (incorrect) + grep blob verify_pack_result \ + | awk -f print_1.awk \ + | sort >actual && + ... + + (correct) + grep blob verify_pack_result | + awk -f print_1.awk | + sort >actual && + ... + - We prefer "test" over "[ ... ]". - We do not write the noiseword "function" in front of shell @@ -140,8 +162,6 @@ For shell scripts specifically (not exhaustive): - We do not use \{m,n\}; - - We do not use -E; - - We do not use ? or + (which are \{0,1\} and \{1,\} respectively in BRE) but that goes without saying as these are ERE elements not BRE (note that \? and \+ are not even part @@ -163,19 +183,137 @@ For shell scripts specifically (not exhaustive): does not have such a problem. + - Even though "local" is not part of POSIX, we make heavy use of it + in our test suite. We do not use it in scripted Porcelains, and + hopefully nobody starts using "local" before all shells that matter + support it (notably, ksh from AT&T Research does not support it yet). + + - Some versions of shell do not understand "export variable=value", + so we write "variable=value" and then "export variable" on two + separate lines. + + - Some versions of dash have broken variable assignment when prefixed + with "local", "export", and "readonly", in that the value to be + assigned goes through field splitting at $IFS unless quoted. + + (incorrect) + local variable=$value + local variable=$(command args) + + (correct) + local variable="$value" + local variable="$(command args)" + + - The common construct + + VAR=VAL command args + + to temporarily set and export environment variable VAR only while + "command args" is running is handy, but this triggers an + unspecified behaviour according to POSIX when used for a command + that is not an external command (like shell functions). Indeed, + dash 0.5.10.2-6 on Ubuntu 20.04, /bin/sh on FreeBSD 13, and AT&T + ksh all make a temporary assignment without exporting the variable, + in such a case. As it does not work portably across shells, do not + use this syntax for shell functions. A common workaround is to do + an explicit export in a subshell, like so: + + (incorrect) + VAR=VAL func args + + (correct) + ( + VAR=VAL && + export VAR && + func args + ) + + but be careful that the effect "func" makes to the variables in the + current shell will be lost across the subshell boundary. + + - Use octal escape sequences (e.g. "\302\242"), not hexadecimal (e.g. + "\xc2\xa2") in printf format strings, since hexadecimal escape + sequences are not portable. + For C programs: - We use tabs to indent, and interpret tabs as taking up to 8 spaces. + - Nested C preprocessor directives are indented after the hash by one + space per nesting level. + + #if FOO + # include + # if BAR + # include + # endif + #endif + - We try to keep to at most 80 characters per line. + - As a Git developer we assume you have a reasonably modern compiler + and we recommend you to enable the DEVELOPER makefile knob to + ensure your patch is clear of all compiler warnings we care about, + by e.g. "echo DEVELOPER=1 >>config.mak". + + - When using DEVELOPER=1 mode, you may see warnings from the compiler + like "error: unused parameter 'foo' [-Werror=unused-parameter]", + which indicates that a function ignores its argument. If the unused + parameter can't be removed (e.g., because the function is used as a + callback and has to match a certain interface), you can annotate + the individual parameters with the UNUSED (or MAYBE_UNUSED) + keyword, like "int foo UNUSED". + - We try to support a wide range of C compilers to compile Git with, - including old ones. That means that you should not use C99 - initializers, even if a lot of compilers grok it. + including old ones. As of Git v2.35.0 Git requires C99 (we check + "__STDC_VERSION__"). You should not use features from a newer C + standard, even if your compiler groks them. + + New C99 features have been phased in gradually, if something's new + in C99 but not used yet don't assume that it's safe to use, some + compilers we target have only partial support for it. These are + considered safe to use: + + . since around 2007 with 2b6854c863a, we have been using + initializer elements which are not computable at load time. E.g.: + + const char *args[] = { "constant", variable, NULL }; + + . since early 2012 with e1327023ea, we have been using an enum + definition whose last element is followed by a comma. This, like + an array initializer that ends with a trailing comma, can be used + to reduce the patch noise when adding a new identifier at the end. + + . since mid 2017 with cbc0f81d, we have been using designated + initializers for struct (e.g. "struct t v = { .val = 'a' };"). + + . since mid 2017 with 512f41cf, we have been using designated + initializers for array (e.g. "int array[10] = { [5] = 2 }"). + + . since early 2021 with 765dc168882, we have been using variadic + macros, mostly for printf-like trace and debug macros. - - Variables have to be declared at the beginning of the block. + . since late 2021 with 44ba10d6, we have had variables declared in + the for loop "for (int i = 0; i < 10; i++)". + + New C99 features that we cannot use yet: + + . %z and %zu as a printf() argument for a size_t (the %z being for + the POSIX-specific ssize_t). Instead you should use + printf("%"PRIuMAX, (uintmax_t)v). These days the MSVC version we + rely on supports %z, but the C library used by MinGW does not. + + . Shorthand like ".a.b = *c" in struct initializations is known to + trip up an older IBM XLC version, use ".a = { .b = *c }" instead. + See the 33665d98 (reftable: make assignments portable to AIX xlc + v12.01, 2022-03-28). + + - Variables have to be declared at the beginning of the block, before + the first statement (i.e. -Wdeclaration-after-statement). It is + encouraged to have a blank line between the end of the declarations + and the first statement in the block. - NULL pointers shall be written as NULL, not as 0. @@ -195,17 +333,63 @@ For C programs: while( condition ) func (bar+1); + - A binary operator (other than ",") and ternary conditional "?:" + have a space on each side of the operator to separate it from its + operands. E.g. "A + 1", not "A+1". + + - A unary operator (other than "." and "->") have no space between it + and its operand. E.g. "(char *)ptr", not "(char *) ptr". + + - Do not explicitly compare an integral value with constant 0 or '\0', + or a pointer value with constant NULL. For instance, to validate that + counted array is initialized but has no elements, write: + + if (!ptr || cnt) + BUG("empty array expected"); + + and not: + + if (ptr == NULL || cnt != 0); + BUG("empty array expected"); + - We avoid using braces unnecessarily. I.e. if (bla) { x = 1; } - is frowned upon. A gray area is when the statement extends - over a few lines, and/or you have a lengthy comment atop of - it. Also, like in the Linux kernel, if there is a long list - of "else if" statements, it can make sense to add braces to - single line blocks. + is frowned upon. But there are a few exceptions: + + - When the statement extends over a few lines (e.g., a while loop + with an embedded conditional, or a comment). E.g.: + + while (foo) { + if (x) + one(); + else + two(); + } + + if (foo) { + /* + * This one requires some explanation, + * so we're better off with braces to make + * it obvious that the indentation is correct. + */ + doit(); + } + + - When there are multiple arms to a conditional and some of them + require braces, enclose even a single line block in braces for + consistency. E.g.: + + if (foo) { + doit(); + } else { + one(); + two(); + three(); + } - We try to avoid assignments in the condition of an "if" statement. @@ -224,12 +408,12 @@ For C programs: Note however that a comment that explains a translatable string to translators uses a convention of starting with a magic token - "TRANSLATORS: " immediately after the opening delimiter, even when - it spans multiple lines. We do not add an asterisk at the beginning - of each line, either. E.g. + "TRANSLATORS: ", e.g. - /* TRANSLATORS: here is a comment that explains the string - to be translated, that follows immediately after it */ + /* + * TRANSLATORS: here is a comment that explains the string to + * be translated, that follows immediately after it. + */ _("Here is a translatable string explained by the above."); - Double negation is often harder to understand than no negation @@ -326,11 +510,52 @@ For C programs: string_list for sorted string lists, a hash map (mapping struct objects) named "struct decorate", amongst other things. - - When you come up with an API, document it. - - - The first #include in C files, except in platform specific - compat/ implementations, should be git-compat-util.h or another - header file that includes it, such as cache.h or builtin.h. + - When you come up with an API, document its functions and structures + in the header file that exposes the API to its callers. Use what is + in "strbuf.h" as a model for the appropriate tone and level of + detail. + + - The first #include in C files, except in platform specific compat/ + implementations and sha1dc/, must be . This + header file insulates other header files and source files from + platform differences, like which system header files must be + included in what order, and what C preprocessor feature macros must + be defined to trigger certain features we expect out of the system. + A collorary to this is that C files should not directly include + system header files themselves. + + There are some exceptions, because certain group of files that + implement an API all have to include the same header file that + defines the API and it is convenient to include + there. Namely: + + - the implementation of the built-in commands in the "builtin/" + directory that include "builtin.h" for the cmd_foo() prototype + definition, + + - the test helper programs in the "t/helper/" directory that include + "t/helper/test-tool.h" for the cmd__foo() prototype definition, + + - the xdiff implementation in the "xdiff/" directory that includes + "xdiff/xinclude.h" for the xdiff machinery internals, + + - the unit test programs in "t/unit-tests/" directory that include + "t/unit-tests/test-lib.h" that gives them the unit-tests + framework, and + + - the source files that implement reftable in the "reftable/" + directory that include "reftable/system.h" for the reftable + internals, + + are allowed to assume that they do not have to include + themselves, as it is included as the first + '#include' in these header files. These headers must be the first + header file to be "#include"d in them, though. + + - A C file must directly include the header files that declare the + functions and the types it uses, except for the functions and types + that are made available to it by including one of the header files + it must include by the previous rule. - If you are planning a new command, consider writing it in shell or perl first, so that changes in semantics can be easily @@ -349,11 +574,72 @@ For C programs: - Use Git's gettext wrappers to make the user interface translatable. See "Marking strings for translation" in po/README. + - Variables and functions local to a given source file should be marked + with "static". Variables that are visible to other source files + must be declared with "extern" in header files. However, function + declarations should not use "extern", as that is already the default. + + - You can launch gdb around your program using the shorthand GIT_DEBUGGER. + Run `GIT_DEBUGGER=1 ./bin-wrappers/git foo` to simply use gdb as is, or + run `GIT_DEBUGGER=" " ./bin-wrappers/git foo` to + use your own debugger and arguments. Example: `GIT_DEBUGGER="ddd --gdb" + ./bin-wrappers/git log` (See `bin-wrappers/wrap-for-bin.sh`.) + + - The primary data structure that a subsystem 'S' deals with is called + `struct S`. Functions that operate on `struct S` are named + `S_()` and should generally receive a pointer to `struct S` as + first parameter. E.g. + + struct strbuf; + + void strbuf_add(struct strbuf *buf, ...); + + void strbuf_reset(struct strbuf *buf); + + is preferred over: + + struct strbuf; + + void add_string(struct strbuf *buf, ...); + + void reset_strbuf(struct strbuf *buf); + + - There are several common idiomatic names for functions performing + specific tasks on a structure `S`: + + - `S_init()` initializes a structure without allocating the + structure itself. + + - `S_release()` releases a structure's contents without freeing the + structure. + + - `S_clear()` is equivalent to `S_release()` followed by `S_init()` + such that the structure is directly usable after clearing it. When + `S_clear()` is provided, `S_init()` shall not allocate resources + that need to be released again. + + - `S_free()` releases a structure's contents and frees the + structure. + + - Function names should be clear and descriptive, accurately reflecting + their purpose or behavior. Arbitrary suffixes that do not add meaningful + context can lead to confusion, particularly for newcomers to the codebase. + + Historically, the '_1' suffix has been used in situations where: + + - A function handles one element among a group that requires similar + processing. + - A recursive function has been separated from its setup phase. + + The '_1' suffix can be used as a concise way to indicate these specific + cases. However, it is recommended to find a more descriptive name wherever + possible to improve the readability and maintainability of the code. + For Perl programs: - Most of the C guidelines above apply. - - We try to support Perl 5.8 and later ("use Perl 5.008"). + - We try to support Perl 5.8.1 and later ("use Perl 5.008001"). - use strict and use warnings are strongly preferred. @@ -379,38 +665,91 @@ For Perl programs: - Learn and use Git.pm if you need that functionality. - - For Emacs, it's useful to put the following in - GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: - - ;; note the first part is useful for C editing, too - ((nil . ((indent-tabs-mode . t) - (tab-width . 8) - (fill-column . 80))) - (cperl-mode . ((cperl-indent-level . 8) - (cperl-extra-newline-before-brace . nil) - (cperl-merge-trailing-else . t)))) - For Python scripts: - - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/). + - We follow PEP-8 (https://peps.python.org/pep-0008/). - - As a minimum, we aim to be compatible with Python 2.6 and 2.7. + - As a minimum, we aim to be compatible with Python 2.7. - Where required libraries do not restrict us to Python 2, we try to also be compatible with Python 3.1 and later. - - When you must differentiate between Unicode literals and byte string - literals, it is OK to use the 'b' prefix. Even though the Python - documentation for version 2.6 does not mention this prefix, it has - been supported since version 2.6.0. + +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 + ''..." 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. + - Do not end a single-sentence error message with a full stop. + + - Do not capitalize the first word, only because it is the first word + in the message ("unable to open '%s'", not "Unable to open '%s'"). But + "SHA-3 not supported" is fine, because the reason the first word is + capitalized is not because it is at the beginning of the sentence, + but because the word would be spelled in capital letters even when + it appeared in the middle of the sentence. + + - Say what the error is first ("cannot open '%s'", not "%s: cannot open"). + + - Enclose the subject of an error inside a pair of single quotes, + e.g. `die(_("unable to open '%s'"), path)`. + + - Unless there is a compelling reason not to, error messages from + porcelain commands should be marked for translation, e.g. + `die(_("bad revision %s"), revision)`. + + - Error messages from the plumbing commands are sometimes meant for + machine consumption and should not be marked for translation, + e.g., `die("bad revision %s", revision)`. + + - BUG("message") are for communicating the specific error to developers, + thus should not be translated. + + +Externally Visible Names + + - For configuration variable names, follow the existing convention: + + . The section name indicates the affected subsystem. + + . The subsection name, if any, indicates which of an unbounded set + of things to set the value for. + + . The variable name describes the effect of tweaking this knob. - - Do not capitalize ("unable to open %s", not "Unable to open %s") + The section and variable names that consist of multiple words are + formed by concatenating the words without punctuation marks (e.g. `-`), + and are broken using bumpyCaps in documentation as a hint to the + reader. - - Say what the error is first ("cannot open %s", not "%s: cannot open") + When choosing the variable namespace, do not use variable name for + specifying possibly unbounded set of things, most notably anything + an end user can freely come up with (e.g. branch names). Instead, + use subsection names or variable values, like the existing variable + branch..description does. Writing Documentation: @@ -428,26 +767,132 @@ Writing Documentation: documentation, please see the documentation-related advice in the Documentation/SubmittingPatches file). + In order to ensure the documentation is inclusive, avoid assuming + that an unspecified example person is male or female, and think + twice before using "he", "him", "she", or "her". Here are some + tips to avoid use of gendered pronouns: + + - Prefer succinctness and matter-of-factly describing functionality + in the abstract. E.g. + + `--short`:: Emit output in the short-format. + + and avoid something like these overly verbose alternatives: + + `--short`:: Use this to emit output in the short-format. + `--short`:: You can use this to get output in the short-format. + `--short`:: A user who prefers shorter output could.... + `--short`:: Should a person and/or program want shorter output, he + she/they/it can... + + This practice often eliminates the need to involve human actors in + your description, but it is a good practice regardless of the + avoidance of gendered pronouns. + + - When it becomes awkward to stick to this style, prefer "you" when + addressing the hypothetical user, and possibly "we" when + discussing how the program might react to the user. E.g. + + You can use this option instead of `--xyz`, but we might remove + support for it in future versions. + + while keeping in mind that you can probably be less verbose, e.g. + + Use this instead of `--xyz`. This option might be removed in future + versions. + + - If you still need to refer to an example person that is + third-person singular, you may resort to "singular they" to avoid + "he/she/him/her", e.g. + + A contributor asks their upstream to pull from them. + + Note that this sounds ungrammatical and unnatural to those who + learned that "they" is only used for third-person plural, e.g. + those who learn English as a second language in some parts of the + world. + Every user-visible change should be reflected in the documentation. The same general rule as for code applies -- imitate the existing conventions. + +Markup: + + Literal parts (e.g. use of command-line options, command names, + branch names, URLs, pathnames (files and directories), configuration and + environment variables) must be typeset as verbatim (i.e. wrapped with + backticks): + `--pretty=oneline` + `git rev-list` + `remote.pushDefault` + `http://git.example.com` + `.git/config` + `GIT_DIR` + `HEAD` + `umask`(2) + + An environment variable must be prefixed with "$" only when referring to its + value and not when referring to the variable itself, in this case there is + nothing to add except the backticks: + `GIT_DIR` is specified + `$GIT_DIR/hooks/pre-receive` + + Word phrases enclosed in `backtick characters` are rendered literally + and will not be further expanded. The use of `backticks` to achieve the + previous rule means that literal examples should not use AsciiDoc + escapes. + Correct: + `--pretty=oneline` + Incorrect: + `\--pretty=oneline` + + Placeholders are spelled in lowercase and enclosed in + angle brackets surrounded by underscores: + __ + __ + + If a placeholder has multiple words, they are separated by dashes: + __ + __ + + When needed, use a distinctive identifier for placeholders, usually + made of a qualification and a type: + __ + __ + + Git's Asciidoc processor has been tailored to treat backticked text + as complex synopsis. When literal and placeholders are mixed, you can + use the backtick notation which will take care of correctly typesetting + the content. + `--jobs ` + `--sort=` + `/.git` + `remote..mirror` + `ssh://[@][:]/` + +As a side effect, backquoted placeholders are correctly typeset, but +this style is not recommended. + +Synopsis Syntax + + The synopsis (a paragraph with [synopsis] attribute) is automatically + formatted by the toolchain and does not need typesetting. + A few commented examples follow to provide reference when writing or modifying command usage strings and synopsis sections in the manual pages: - Placeholders are spelled in lowercase and enclosed in angle brackets: - - --sort= - --abbrev[=] - Possibility of multiple occurrences is indicated by three dots: ... (One or more of .) Optional parts are enclosed in square brackets: - [] - (Zero or one .) + [...] + (Zero or more of .) + + An optional parameter needs to be typeset with unconstrained pairs + [] --exec-path[=] (Option with an optional argument. Note that the "=" is inside the @@ -457,10 +902,20 @@ Writing Documentation: (Zero or more of . Note that the dots are inside, not outside the brackets.) - Multiple alternatives are indicated with vertical bar: + Multiple alternatives are indicated with vertical bars: [-q | --quiet] [--utf8 | --no-utf8] + Use spacing around "|" token(s), but not immediately after opening or + before closing a [] or () pair: + Do: [-q | --quiet] + Don't: [-q|--quiet] + + Don't use spacing around "|" tokens when they're used to separate the + alternate arguments of an option: + Do: --track[=(direct|inherit)] + Don't: --track[=(direct | inherit)] + Parentheses are used for grouping: [(|)...] (Any number of either or . Parens are needed to make @@ -469,7 +924,7 @@ Writing Documentation: [(-p )...] (Any number of option -p, each with one argument.) - git remote set-head (-a | -d | ) + git remote set-head (-a|-d|) (One and only one of "-a", "-d" or "" _must_ (no square brackets) be provided.) @@ -485,26 +940,6 @@ Writing Documentation: the user would type into a shell and use 'Git' (uppercase first letter) when talking about the version control system and its properties. - A few commented examples follow to provide reference when writing or - modifying paragraphs or option/command explanations that contain options - or commands: - - Literal examples (e.g. use of command-line options, command names, and - configuration variables) are typeset in monospace, and if you can use - `backticks around word phrases`, do so. - `--pretty=oneline` - `git rev-list` - `remote.pushdefault` - - Word phrases enclosed in `backtick characters` are rendered literally - and will not be further expanded. The use of `backticks` to achieve the - previous rule means that literal examples should not use AsciiDoc - escapes. - Correct: - `--pretty=oneline` - Incorrect: - `\--pretty=oneline` - If some place in the documentation needs to typeset a command usage example with inline substitutions, it is fine to use +monospaced and inline substituted text+ instead of `monospaced literal text`, and with diff --git a/Documentation/DecisionMaking.txt b/Documentation/DecisionMaking.txt new file mode 100644 index 00000000000000..b43c472ae598ed --- /dev/null +++ b/Documentation/DecisionMaking.txt @@ -0,0 +1,74 @@ +Decision-Making Process in the Git Project +========================================== + +Introduction +------------ +This document describes the current decision-making process in the Git +project. It is a descriptive rather than prescriptive doc; that is, we want to +describe how things work in practice rather than explicitly recommending any +particular process or changes to the current process. + +Here we document how the project makes decisions for discussions +(with or without patches), in scale larger than an individual patch +series (which is fully covered by the SubmittingPatches document). + + +Larger Discussions (with patches) +--------------------------------- +As with discussions on an individual patch series, starting a larger-scale +discussion often begins by sending a patch or series to the list. This might +take the form of an initial design doc, with implementation following in later +iterations of the series (for example, +link:https://lore.kernel.org/git/0169ce6fb9ccafc089b74ae406db0d1a8ff8ac65.1688165272.git.steadmon@google.com/[adding unit tests] or +link:https://lore.kernel.org/git/20200420235310.94493-1-emilyshaffer@google.com/[config-based hooks]), +or it might include a full implementation from the beginning. +In either case, discussion progresses the same way for an individual patch series, +until consensus is reached or the topic is dropped. + + +Larger Discussions (without patches) +------------------------------------ +Occasionally, larger discussions might occur without an associated patch series. +These may be very large-scale technical decisions that are beyond the scope of +even a single large patch series, or they may be more open-ended, +policy-oriented discussions (examples: +link:https://lore.kernel.org/git/ZZ77NQkSuiRxRDwt@nand.local/[introducing Rust] +or link:https://lore.kernel.org/git/YHofmWcIAidkvJiD@google.com/[improving submodule UX]). +In either case, discussion progresses as described above for general patch series. + +For larger discussions without a patch series or other concrete implementation, +it may be hard to judge when consensus has been reached, as there are not any +official guidelines. If discussion stalls at this point, it may be helpful to +restart discussion with an RFC patch series (such as a partial, unfinished +implementation or proof of concept) that can be more easily debated. + +When consensus is reached that it is a good idea, the original +proposer is expected to coordinate the effort to make it happen, +with help from others who were involved in the discussion, as +needed. + +For decisions that require code changes, it is often the case that the original +proposer will follow up with a patch series, although it is also common for +other interested parties to provide an implementation (or parts of the +implementation, for very large changes). + +For non-technical decisions such as community norms or processes, it is up to +the community as a whole to implement and sustain agreed-upon changes. +The project leadership committee (PLC) may help the implementation of +policy decisions. + + +Other Discussion Venues +----------------------- +Occasionally decision proposals are presented off-list, e.g. at the semi-regular +Contributors' Summit. While higher-bandwidth face-to-face discussion is often +useful for quickly reaching consensus among attendees, generally we expect to +summarize the discussion in notes that can later be presented on-list. For an +example, see the thread +link:https://lore.kernel.org/git/AC2EB721-2979-43FD-922D-C5076A57F24B@jramsay.com.au/[Notes +from Git Contributor Summit, Los Angeles (April 5, 2020)] by James Ramsay. + +We prefer that "official" discussion happens on the list so that the full +community has opportunity to engage in discussion. This also means that the +mailing list archives contain a more-or-less complete history of project +discussions and decisions. diff --git a/Documentation/Makefile b/Documentation/Makefile index cea0e7ae3db37d..aedfe99d1d3588 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -1,23 +1,47 @@ +# Import tree-wide shared Makefile behavior and libraries +include ../shared.mak + +.PHONY: FORCE + # Guard against environment variables MAN1_TXT = MAN5_TXT = MAN7_TXT = +HOWTO_TXT = +DOC_DEP_TXT = TECH_DOCS = 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 +MAN1_TXT += scalar.txt +# man5 / man7 guides (note: new guides should also be added to command-list.txt) MAN5_TXT += gitattributes.txt +MAN5_TXT += gitformat-bundle.txt +MAN5_TXT += gitformat-chunk.txt +MAN5_TXT += gitformat-commit-graph.txt +MAN5_TXT += gitformat-index.txt +MAN5_TXT += gitformat-pack.txt +MAN5_TXT += gitformat-signature.txt MAN5_TXT += githooks.txt MAN5_TXT += gitignore.txt +MAN5_TXT += gitmailmap.txt MAN5_TXT += gitmodules.txt +MAN5_TXT += gitprotocol-capabilities.txt +MAN5_TXT += gitprotocol-common.txt +MAN5_TXT += gitprotocol-http.txt +MAN5_TXT += gitprotocol-pack.txt +MAN5_TXT += gitprotocol-v2.txt MAN5_TXT += gitrepository-layout.txt MAN5_TXT += gitweb.conf.txt @@ -26,22 +50,39 @@ MAN7_TXT += gitcore-tutorial.txt MAN7_TXT += gitcredentials.txt MAN7_TXT += gitcvs-migration.txt MAN7_TXT += gitdiffcore.txt +MAN7_TXT += giteveryday.txt +MAN7_TXT += gitfaq.txt MAN7_TXT += gitglossary.txt +MAN7_TXT += gitpacking.txt MAN7_TXT += gitnamespaces.txt +MAN7_TXT += gitremote-helpers.txt MAN7_TXT += gitrevisions.txt +MAN7_TXT += gitsubmodules.txt MAN7_TXT += gittutorial-2.txt MAN7_TXT += gittutorial.txt MAN7_TXT += gitworkflows.txt +HOWTO_TXT += $(wildcard howto/*.txt) + +DOC_DEP_TXT += $(wildcard *.txt) +DOC_DEP_TXT += $(wildcard config/*.txt) +DOC_DEP_TXT += $(wildcard includes/*.txt) + +ifdef MAN_FILTER +MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)) +else MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT) +MAN_FILTER = $(MAN_TXT) +endif + MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT)) MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT)) +GIT_MAN_REF = master -OBSOLETE_HTML = git-remote-helpers.html -DOC_HTML = $(MAN_HTML) $(OBSOLETE_HTML) +OBSOLETE_HTML += everyday.html +OBSOLETE_HTML += git-remote-helpers.html ARTICLES += howto-index -ARTICLES += everyday ARTICLES += git-tools ARTICLES += git-bisect-lk2009 # with their own formatting rules. @@ -61,28 +102,43 @@ SP_ARTICLES += howto/rebuild-from-update-hook SP_ARTICLES += howto/rebase-from-internal-branch SP_ARTICLES += howto/keep-canonical-history-correct SP_ARTICLES += howto/maintain-git +SP_ARTICLES += howto/coordinate-embargoed-releases API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt))) SP_ARTICLES += $(API_DOCS) -TECH_DOCS += technical/http-protocol -TECH_DOCS += technical/index-format -TECH_DOCS += technical/pack-format +TECH_DOCS += DecisionMaking +TECH_DOCS += ReviewingGuidelines +TECH_DOCS += MyFirstContribution +TECH_DOCS += MyFirstObjectWalk +TECH_DOCS += SubmittingPatches +TECH_DOCS += ToolsForGit +TECH_DOCS += technical/bitmap-format +TECH_DOCS += technical/build-systems +TECH_DOCS += technical/bundle-uri +TECH_DOCS += technical/hash-function-transition +TECH_DOCS += technical/long-running-process-protocol +TECH_DOCS += technical/multi-pack-index TECH_DOCS += technical/pack-heuristics -TECH_DOCS += technical/pack-protocol -TECH_DOCS += technical/protocol-capabilities -TECH_DOCS += technical/protocol-common +TECH_DOCS += technical/parallel-checkout +TECH_DOCS += technical/partial-clone +TECH_DOCS += technical/platform-support TECH_DOCS += technical/racy-git +TECH_DOCS += technical/reftable +TECH_DOCS += technical/scalar TECH_DOCS += technical/send-pack-pipeline TECH_DOCS += technical/shallow TECH_DOCS += technical/trivial-merge +TECH_DOCS += technical/unit-tests SP_ARTICLES += $(TECH_DOCS) SP_ARTICLES += technical/api-index -DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES)) +ARTICLES_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES)) +HTML_FILTER ?= $(ARTICLES_HTML) $(OBSOLETE_HTML) +DOC_HTML = $(MAN_HTML) $(filter $(HTML_FILTER),$(ARTICLES_HTML) $(OBSOLETE_HTML)) -DOC_MAN1 = $(patsubst %.txt,%.1,$(MAN1_TXT)) -DOC_MAN5 = $(patsubst %.txt,%.5,$(MAN5_TXT)) -DOC_MAN7 = $(patsubst %.txt,%.7,$(MAN7_TXT)) +DOC_MAN1 = $(patsubst %.txt,%.1,$(filter $(MAN_FILTER),$(MAN1_TXT))) +DOC_MAN5 = $(patsubst %.txt,%.5,$(filter $(MAN_FILTER),$(MAN5_TXT))) +DOC_MAN7 = $(patsubst %.txt,%.7,$(filter $(MAN_FILTER),$(MAN7_TXT))) prefix ?= $(HOME) bindir ?= $(prefix)/bin @@ -97,6 +153,13 @@ man7dir = $(mandir)/man7 ASCIIDOC = asciidoc ASCIIDOC_EXTRA = +ASCIIDOC_HTML = xhtml11 +ASCIIDOC_DOCBOOK = docbook +ASCIIDOC_CONF = -f asciidoc.conf +ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) +ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS +TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML) +TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK) MANPAGE_XSL = manpage-normal.xsl XMLTO = xmlto XMLTO_EXTRA = @@ -110,6 +173,7 @@ INSTALL_INFO = install-info DOCBOOK2X_TEXI = docbook2x-texi DBLATEX = dblatex ASCIIDOC_DBLATEX_DIR = /etc/asciidoc/dblatex +DBLATEX_COMMON = -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty ifndef PERL_PATH PERL_PATH = /usr/bin/perl endif @@ -117,32 +181,13 @@ endif -include ../config.mak.autogen -include ../config.mak -# -# For docbook-xsl ... -# -1.68.1, no extra settings are needed? -# 1.69.0, set ASCIIDOC_ROFF? -# 1.69.1-1.71.0, set DOCBOOK_SUPPRESS_SP? -# 1.71.1, set ASCIIDOC_ROFF? -# 1.72.0, set DOCBOOK_XSL_172. -# 1.73.0-, no extra settings are needed -# +# Set GIT_VERSION_OVERRIDE such that version_gen knows to substitute +# GIT_VERSION in case it was set by the user. +GIT_VERSION_OVERRIDE := $(GIT_VERSION) -ifdef DOCBOOK_XSL_172 -ASCIIDOC_EXTRA += -a git-asciidoc-no-roff -MANPAGE_XSL = manpage-1.72.xsl -else - ifndef ASCIIDOC_ROFF - # docbook-xsl after 1.72 needs the regular XSL, but will not - # pass-thru raw roff codes from asciidoc.conf, so turn them off. - ASCIIDOC_EXTRA += -a git-asciidoc-no-roff - endif -endif -ifdef MAN_BOLD_LITERAL +ifndef NO_MAN_BOLD_LITERAL XMLTO_EXTRA += -m manpage-bold-literal.xsl endif -ifdef DOCBOOK_SUPPRESS_SP -XMLTO_EXTRA += -m manpage-suppress-sp.xsl -endif # Newer DocBook stylesheet emits warning cruft in the output when # this is not set, and if set it shows an absolute link. Older @@ -153,20 +198,36 @@ endif ifndef MAN_BASE_URL MAN_BASE_URL = file://$(htmldir)/ endif -XMLTO_EXTRA += -m manpage-base-url.xsl - -# If your target system uses GNU groff, it may try to render -# apostrophes as a "pretty" apostrophe using unicode. This breaks -# cut&paste, so you should set GNU_ROFF to force them to be ASCII -# apostrophes. Unfortunately does not work with non-GNU roff. -ifdef GNU_ROFF -XMLTO_EXTRA += -m manpage-quote-apos.xsl +XMLTO_EXTRA += --stringparam man.base.url.for.relative.links='$(MAN_BASE_URL)' + +ifdef USE_ASCIIDOCTOR +ASCIIDOC = asciidoctor +ASCIIDOC_CONF = +ASCIIDOC_HTML = xhtml5 +ASCIIDOC_DOCBOOK = docbook5 +ASCIIDOC_EXTRA += -acompat-mode -atabsize=8 +ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions +ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;' +ASCIIDOC_EXTRA += -adocinfo=shared +ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS +DBLATEX_COMMON = +XMLTO_EXTRA += --skip-validation +XMLTO_EXTRA += -x manpage.xsl + +asciidoctor-extensions.rb: asciidoctor-extensions.rb.in FORCE + $(QUIET_GEN)$(call version_gen,"$(shell pwd)/..",$<,$@) +else +asciidoc.conf: asciidoc.conf.in FORCE + $(QUIET_GEN)$(call version_gen,"$(shell pwd)/..",$<,$@) endif +ASCIIDOC_DEPS += docinfo.html + SHELL_PATH ?= $(SHELL) # Shell quote; SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH)) +ASCIIDOC_EXTRA += -abuild_dir='$(shell pwd)' ifdef DEFAULT_PAGER DEFAULT_PAGER_SQ = $(subst ','\'',$(DEFAULT_PAGER)) ASCIIDOC_EXTRA += -a 'git-default-pager=$(DEFAULT_PAGER_SQ)' @@ -177,32 +238,6 @@ DEFAULT_EDITOR_SQ = $(subst ','\'',$(DEFAULT_EDITOR)) ASCIIDOC_EXTRA += -a 'git-default-editor=$(DEFAULT_EDITOR_SQ)' endif -QUIET_SUBDIR0 = +$(MAKE) -C # space to separate -C and subdir -QUIET_SUBDIR1 = - -ifneq ($(findstring $(MAKEFLAGS),w),w) -PRINT_DIR = --no-print-directory -else # "make -w" -NO_SUBDIR = : -endif - -ifneq ($(findstring $(MAKEFLAGS),s),s) -ifndef V - QUIET_ASCIIDOC = @echo ' ' ASCIIDOC $@; - QUIET_XMLTO = @echo ' ' XMLTO $@; - QUIET_DB2TEXI = @echo ' ' DB2TEXI $@; - QUIET_MAKEINFO = @echo ' ' MAKEINFO $@; - QUIET_DBLATEX = @echo ' ' DBLATEX $@; - QUIET_XSLTPROC = @echo ' ' XSLTPROC $@; - QUIET_GEN = @echo ' ' GEN $@; - QUIET_STDERR = 2> /dev/null - QUIET_SUBDIR0 = +@subdir= - QUIET_SUBDIR1 = ;$(NO_SUBDIR) echo ' ' SUBDIR $$subdir; \ - $(MAKE) $(PRINT_DIR) -C $$subdir - export V -endif -endif - all: html man html: $(DOC_HTML) @@ -243,24 +278,21 @@ install-pdf: pdf install-html: html '$(SHELL_PATH_SQ)' ./install-webdoc.sh $(DESTDIR)$(htmldir) -../GIT-VERSION-FILE: FORCE - $(QUIET_SUBDIR0)../ $(QUIET_SUBDIR1) GIT-VERSION-FILE - --include ../GIT-VERSION-FILE +mergetools_txt = mergetools-diff.txt mergetools-merge.txt # # Determine "include::" file references in asciidoc files. # docdep_prereqs = \ - mergetools-list.made $(mergetools_txt) \ + $(mergetools_txt) \ cmd-list.made $(cmds_txt) -doc.dep : $(docdep_prereqs) $(wildcard *.txt) build-docdep.perl - $(QUIET_GEN)$(RM) $@+ $@ && \ - $(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \ - mv $@+ $@ +doc.dep : $(docdep_prereqs) $(DOC_DEP_TXT) build-docdep.perl + $(QUIET_GEN)$(PERL_PATH) ./build-docdep.perl "$(shell pwd)" >$@ $(QUIET_STDERR) +ifneq ($(MAKECMDGOALS),clean) -include doc.dep +endif cmds_txt = cmds-ancillaryinterrogators.txt \ cmds-ancillarymanipulators.txt \ @@ -269,132 +301,130 @@ cmds_txt = cmds-ancillaryinterrogators.txt \ cmds-plumbingmanipulators.txt \ cmds-synchingrepositories.txt \ cmds-synchelpers.txt \ + cmds-guide.txt \ + cmds-developerinterfaces.txt \ + cmds-userinterfaces.txt \ cmds-purehelpers.txt \ cmds-foreignscminterface.txt $(cmds_txt): cmd-list.made cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT) - $(QUIET_GEN)$(RM) $@ && \ - $(PERL_PATH) ./cmd-list.perl ../command-list.txt $(QUIET_STDERR) && \ + $(QUIET_GEN)$(PERL_PATH) ./cmd-list.perl .. . $(cmds_txt) && \ date >$@ -mergetools_txt = mergetools-diff.txt mergetools-merge.txt +mergetools-%.txt: generate-mergetool-list.sh ../git-mergetool--lib.sh $(wildcard ../mergetools/*) +mergetools-diff.txt: + $(QUIET_GEN)$(SHELL_PATH) ./generate-mergetool-list.sh .. diff $@ +mergetools-merge.txt: + $(QUIET_GEN)$(SHELL_PATH) ./generate-mergetool-list.sh .. merge $@ -$(mergetools_txt): mergetools-list.made +TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK)) -mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*) - $(QUIET_GEN)$(RM) $@ && \ - $(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && \ - . ../git-mergetool--lib.sh && \ - show_tool_names can_diff "* " || :' >mergetools-diff.txt && \ - $(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && \ - . ../git-mergetool--lib.sh && \ - show_tool_names can_merge "* " || :' >mergetools-merge.txt && \ - date >$@ +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) -rf .build/ $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 $(RM) *.texi *.texi+ *.texi++ git.info gitman.info $(RM) *.pdf $(RM) howto-index.txt howto/*.html doc.dep $(RM) technical/*.html technical/api-index.txt + $(RM) SubmittingPatches.txt $(RM) $(cmds_txt) $(mergetools_txt) *.made - $(RM) manpage-base-url.xsl - -$(MAN_HTML): %.html : %.txt asciidoc.conf - $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \ - $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \ - mv $@+ $@ - -$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf - $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - $(ASCIIDOC) -b xhtml11 -f asciidoc.conf \ - $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \ - mv $@+ $@ - -manpage-base-url.xsl: manpage-base-url.xsl.in - sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@ - -%.1 %.5 %.7 : %.xml manpage-base-url.xsl - $(QUIET_XMLTO)$(RM) $@ && \ - $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< - -%.xml : %.txt asciidoc.conf - $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - $(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \ - $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \ - mv $@+ $@ - -user-manual.xml: user-manual.txt user-manual.conf - $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b docbook -d article -o $@+ $< && \ - mv $@+ $@ + $(RM) GIT-ASCIIDOCFLAGS + $(RM) asciidoc.conf asciidoctor-extensions.rb + $(RM) -rf tmp-meson-diff + +docinfo.html: docinfo-html.in + $(QUIET_GEN)$(RM) $@ && cat $< >$@ + +$(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS) + $(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@ $< + +$(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS) + $(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $< + +manpage-prereqs := $(wildcard manpage*.xsl) +manpage-cmd = $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< + +%.1 : %.xml $(manpage-prereqs) + $(manpage-cmd) +%.5 : %.xml $(manpage-prereqs) + $(manpage-cmd) +%.7 : %.xml $(manpage-prereqs) + $(manpage-cmd) + +%.xml : %.txt $(ASCIIDOC_DEPS) + $(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $< + +user-manual.xml: user-manual.txt $(ASCIIDOC_DEPS) + $(QUIET_ASCIIDOC)$(TXT_TO_XML) -d book -o $@ $< technical/api-index.txt: technical/api-index-skel.txt \ technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS)) - $(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh + $(QUIET_GEN)'$(SHELL_PATH_SQ)' technical/api-index.sh ./technical ./technical/api-index.txt technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ -$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt asciidoc.conf - $(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \ - $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt +$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt \ + $(ASCIIDOC_DEPS) + $(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt + +SubmittingPatches.txt: SubmittingPatches + $(QUIET_GEN) cp $< $@ XSLT = docbook.xsl -XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css +XSLTOPTS = +XSLTOPTS += --xinclude +XSLTOPTS += --stringparam html.stylesheet docbook-xsl.css +XSLTOPTS += --param generate.consistent.ids 1 user-manual.html: user-manual.xml $(XSLT) - $(QUIET_XSLTPROC)$(RM) $@+ $@ && \ - xsltproc $(XSLTOPTS) -o $@+ $(XSLT) $< && \ - mv $@+ $@ + $(QUIET_XSLTPROC)xsltproc $(XSLTOPTS) -o $@ $(XSLT) $< git.info: user-manual.texi $(QUIET_MAKEINFO)$(MAKEINFO) --no-split -o $@ user-manual.texi user-manual.texi: user-manual.xml - $(QUIET_DB2TEXI)$(RM) $@+ $@ && \ - $(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@++ && \ - $(PERL_PATH) fix-texi.perl <$@++ >$@+ && \ - rm $@++ && \ - mv $@+ $@ + $(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@+ && \ + $(PERL_PATH) fix-texi.perl <$@+ >$@ && \ + $(RM) $@+ user-manual.pdf: user-manual.xml - $(QUIET_DBLATEX)$(RM) $@+ $@ && \ - $(DBLATEX) -o $@+ -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty $< && \ - mv $@+ $@ - -gitman.texi: $(MAN_XML) cat-texi.perl - $(QUIET_DB2TEXI)$(RM) $@+ $@ && \ - ($(foreach xml,$(MAN_XML),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \ - --to-stdout $(xml) &&) true) > $@++ && \ - $(PERL_PATH) cat-texi.perl $@ <$@++ >$@+ && \ - rm $@++ && \ - mv $@+ $@ + $(QUIET_DBLATEX)$(DBLATEX) -o $@ $(DBLATEX_COMMON) $< + +gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl + $(QUIET_DB2TEXI) \ + ($(foreach xml,$(sort $(MAN_XML)),xsltproc -o $(xml)+ texi.xsl $(xml) && \ + $(DOCBOOK2X_TEXI) --encoding=UTF-8 --to-stdout $(xml)+ && \ + $(RM) $(xml)+ &&) true) > $@+ && \ + $(PERL_PATH) cat-texi.perl $@ <$@+ >$@ && \ + $(RM) $@+ gitman.info: gitman.texi - $(QUIET_MAKEINFO)$(MAKEINFO) --no-split --no-validate $*.texi + $(QUIET_MAKEINFO)$(MAKEINFO) --no-split --no-validate $< $(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml - $(QUIET_DB2TEXI)$(RM) $@+ $@ && \ - $(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@+ && \ - mv $@+ $@ + $(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@ -howto-index.txt: howto-index.sh $(wildcard howto/*.txt) - $(QUIET_GEN)$(RM) $@+ $@ && \ - '$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(wildcard howto/*.txt)) >$@+ && \ - mv $@+ $@ +howto-index.txt: howto/howto-index.sh $(HOWTO_TXT) + $(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto/howto-index.sh $(sort $(HOWTO_TXT)) >$@ -$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt - $(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 $*.txt +$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt $(ASCIIDOC_DEPS) + $(QUIET_ASCIIDOC)$(TXT_TO_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 - $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - sed -e '1,/^$$/d' $< | $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 - >$@+ && \ - mv $@+ $@ +$(patsubst %.txt,%.html,$(HOWTO_TXT)): %.html : %.txt $(ASCIIDOC_DEPS) + $(QUIET_ASCIIDOC) \ + sed -e '1,/^$$/d' $< | \ + $(TXT_TO_HTML) - >$@ install-webdoc : html '$(SHELL_PATH_SQ)' ./install-webdoc.sh $(WEBDOC_DEST) @@ -409,16 +439,88 @@ require-manrepo:: then echo "git-manpages repository must exist at $(MAN_REPO)"; exit 1; fi quick-install-man: require-manrepo - '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO) $(DESTDIR)$(mandir) + '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO) $(DESTDIR)$(mandir) $(GIT_MAN_REF) require-htmlrepo:: @if test ! -d $(HTML_REPO); \ then echo "git-htmldocs repository must exist at $(HTML_REPO)"; exit 1; fi quick-install-html: require-htmlrepo - '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir) + '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir) $(GIT_MAN_REF) print-man1: @for i in $(MAN1_TXT); do echo $$i; done +## Lint: gitlink +LINT_DOCS_GITLINK = $(patsubst %.txt,.build/lint-docs/gitlink/%.ok,$(HOWTO_TXT) $(DOC_DEP_TXT)) +$(LINT_DOCS_GITLINK): lint-gitlink.perl +$(LINT_DOCS_GITLINK): .build/lint-docs/gitlink/%.ok: %.txt + $(call mkdir_p_parent_template) + $(QUIET_LINT_GITLINK)$(PERL_PATH) lint-gitlink.perl \ + $< \ + $(HOWTO_TXT) $(DOC_DEP_TXT) \ + --section=1 $(MAN1_TXT) \ + --section=5 $(MAN5_TXT) \ + --section=7 $(MAN7_TXT) >$@ +.PHONY: lint-docs-gitlink +lint-docs-gitlink: $(LINT_DOCS_GITLINK) + +## Lint: man-end-blurb +LINT_DOCS_MAN_END_BLURB = $(patsubst %.txt,.build/lint-docs/man-end-blurb/%.ok,$(MAN_TXT)) +$(LINT_DOCS_MAN_END_BLURB): lint-man-end-blurb.perl +$(LINT_DOCS_MAN_END_BLURB): .build/lint-docs/man-end-blurb/%.ok: %.txt + $(call mkdir_p_parent_template) + $(QUIET_LINT_MANEND)$(PERL_PATH) lint-man-end-blurb.perl $< >$@ +.PHONY: lint-docs-man-end-blurb + +## Lint: man-section-order +LINT_DOCS_MAN_SECTION_ORDER = $(patsubst %.txt,.build/lint-docs/man-section-order/%.ok,$(MAN_TXT)) +$(LINT_DOCS_MAN_SECTION_ORDER): lint-man-section-order.perl +$(LINT_DOCS_MAN_SECTION_ORDER): .build/lint-docs/man-section-order/%.ok: %.txt + $(call mkdir_p_parent_template) + $(QUIET_LINT_MANSEC)$(PERL_PATH) lint-man-section-order.perl $< >$@ +.PHONY: lint-docs-man-section-order +lint-docs-man-section-order: $(LINT_DOCS_MAN_SECTION_ORDER) + +.PHONY: lint-docs-fsck-msgids +LINT_DOCS_FSCK_MSGIDS = .build/lint-docs/fsck-msgids.ok +$(LINT_DOCS_FSCK_MSGIDS): lint-fsck-msgids.perl +$(LINT_DOCS_FSCK_MSGIDS): ../fsck.h fsck-msgids.txt + $(call mkdir_p_parent_template) + $(QUIET_GEN)$(PERL_PATH) lint-fsck-msgids.perl \ + ../fsck.h fsck-msgids.txt $@ + +lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS) + +lint-docs-manpages: + $(QUIET_GEN)./lint-manpages.sh + +.PHONY: lint-docs-meson +lint-docs-meson: + @# awk acts up when trying to match single quotes, so we use \047 instead. + @mkdir -p tmp-meson-diff && \ + awk "/^manpages = {$$/ {flag=1 ; next } /^}$$/ { flag=0 } flag { gsub(/^ \047/, \"\"); gsub(/\047 : [157],\$$/, \"\"); print }" meson.build | \ + grep -v -e '#' -e '^$$' | \ + sort >tmp-meson-diff/meson.txt && \ + ls git*.txt scalar.txt | grep -v -e git-bisect-lk2009.txt -e git-tools.txt >tmp-meson-diff/actual.txt && \ + if ! cmp tmp-meson-diff/meson.txt tmp-meson-diff/actual.txt; then \ + echo "Meson man pages differ from actual man pages:"; \ + diff -u tmp-meson-diff/meson.txt tmp-meson-diff/actual.txt; \ + exit 1; \ + fi + +## Lint: list of targets above +.PHONY: lint-docs +lint-docs: lint-docs-fsck-msgids +lint-docs: lint-docs-gitlink +lint-docs: lint-docs-man-end-blurb +lint-docs: lint-docs-man-section-order +lint-docs: lint-docs-manpages +lint-docs: lint-docs-meson + +ifeq ($(wildcard po/Makefile),po/Makefile) +doc-l10n install-l10n:: + $(MAKE) -C po $@ +endif + .PHONY: FORCE diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt new file mode 100644 index 00000000000000..e41654c00a68e0 --- /dev/null +++ b/Documentation/MyFirstContribution.txt @@ -0,0 +1,1395 @@ +My First Contribution to the Git Project +======================================== +:sectanchors: + +[[summary]] +== 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]] +=== 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]] +=== 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-help]] +=== Getting Help + +If you get stuck, you can seek help in the following places. + +==== git@vger.kernel.org + +This is the main Git project mailing list where code reviews, version +announcements, design discussions, and more take place. Those interested in +contributing are welcome to post questions here. The Git list requires +plain-text-only emails and prefers inline and bottom-posting when replying to +mail; you will be CC'd in all replies to you. Optionally, you can subscribe to +the list by sending an email to +(see https://subspace.kernel.org/subscribing.html for details). +The https://lore.kernel.org/git[archive] of this mailing list is +available to view in a browser. + +==== https://groups.google.com/forum/#!forum/git-mentoring[git-mentoring@googlegroups.com] + +This mailing list is targeted to new contributors and was created as a place to +post questions and receive answers outside of the public eye of the main list. +Veteran contributors who are especially interested in helping mentor newcomers +are present on the list. In order to avoid search indexers, group membership is +required to view messages; anyone can join and no approval is required. + +==== https://web.libera.chat/#git-devel[#git-devel] on Libera Chat + +This IRC channel is for conversations between Git contributors. If someone is +currently online and knows the answer to your question, you can receive help +in real time. Otherwise, you can read the +https://colabti.org/irclogger/irclogger_logs/git-devel[scrollback] to see +whether someone answered you. IRC does not allow offline private messaging, so +if you try to private message someone and then log out of IRC, they cannot +respond to you. It's better to ask your questions in the channel so that you +can be answered if you disconnect and so that others can learn from the +conversation. + +[[getting-started]] +== Getting Started + +[[cloning]] +=== Clone the Git Repository + +Git is mirrored in a number of locations. Clone the repository from one of them; +https://git-scm.com/downloads suggests one of the best places to clone from is +the mirror on GitHub. + +---- +$ git clone https://github.com/git/git git +$ cd git +---- + +[[dependencies]] +=== Installing Dependencies + +To build Git from source, you need to have a handful of dependencies installed +on your system. For a hint of what's needed, you can take a look at +`INSTALL`, paying close attention to the section about Git's dependencies on +external programs and libraries. That document mentions a way to "test-drive" +our freshly built Git without installing; that's the method we'll be using in +this tutorial. + +Make sure that your environment has everything you need by building your brand +new clone of Git from the above step: + +---- +$ make +---- + +NOTE: The Git build is parallelizable. `-j#` is not included above but you can +use it as you prefer, here and elsewhere. + +[[identify-problem]] +=== Identify Problem to Solve + +//// +Use + to indicate fixed-width here; couldn't get ` to work nicely with the +quotes around "Pony Saying 'Um, Hello'". +//// +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`.) + +[[setup-workspace]] +=== 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 document and base it on the appropriate branch. + +For the purposes of this document, 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 a topic +with multiple patches up for review simultaneously. + +[[code-it-up]] +== Code It Up! + +NOTE: A reference implementation can be found at +https://github.com/nasamuffin/git/tree/psuh. + +[[add-new-command]] +=== Adding a New Command + +Lots of the subcommands are written as builtins, which means they are +implemented in C and compiled into the main `git` executable. Implementing the +very simple `psuh` command as a built-in will demonstrate the structure of the +codebase, the internal API, and the process of working together as a contributor +with the reviewers and maintainer to integrate this change into the system. + +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 it, 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 declaration of psuh; open up `builtin.h`, find the +declaration for `cmd_pull`, and add a new line for `psuh` immediately before it, +in order to keep the declarations alphabetically sorted: + +---- +int cmd_psuh(int argc, const char **argv, const char *prefix); +---- + +Be sure to `#include "builtin.h"` in your `psuh.c`. You'll also need to +`#include "gettext.h"` to use functions related to printing output text. + +Go ahead and add some throwaway printf to the `cmd_psuh` 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 tutorial, is user-facing. That means it needs to be +localizable. Take a look at `po/README` under "Marking strings for translation". +Throughout the tutorial, 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/pull.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. + +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 mimicking `push`. Find the line where +`cmd_push` is registered, copy it, and modify it for `cmd_psuh`, placing the new +line in alphabetical order (immediately before `cmd_pull`). + +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 the +`bin-wrappers` directory. + +---- +$ ./bin-wrappers/git psuh +---- + +Check it out! You've got a command! Nice work! Let's commit this. + +`git status` reveals modified `Makefile`, `builtin.h`, and `git.c` as well as +untracked `builtin/psuh.c` and `git-psuh`. First, let's take care of the binary, +which should be ignored. Open `.gitignore` in your editor, find `/git-pull`, and +add an entry for your new command in alphabetical order: + +---- +... +/git-prune-packed +/git-psuh +/git-pull +/git-push +/git-quiltimport +/git-range-diff +... +---- + +Checking `git status` again should show that `git-psuh` has been removed from +the untracked list and `.gitignore` has been added to the modified list. Now we +can stage and commit: + +---- +$ git add Makefile builtin.h builtin/psuh.c git.c .gitignore +$ git commit -s +---- + +You will be presented with your editor in order to write a commit message. Start +the commit with a 50-column or less subject line, including the name of the +component you're working on, followed by a blank line (always required) and then +the body of your commit message, which should provide the bulk of the context. +Remember to be explicit and provide the "Why" of your change, especially if it +couldn't easily be understood from your diff. When editing your commit message, +don't remove the `Signed-off-by` trailer which was added by `-s` above. + +---- +psuh: add a 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 sign-off line (`-s`) indicates that you agree to +the Developer's Certificate of Origin 1.1 (see the +`Documentation/SubmittingPatches` +++[[dco]]+++ header). + +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]] +=== Implementation + +It's probably useful to do at least something besides printing 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, keeping +existing `printf()` calls in place: + +---- + int i; + + ... + + printf(Q_("Your args (there is %d):\n", + "Your args (there are %d):\n", + argc), + argc); + for (i = 0; i < argc; i++) + printf("%d: %s\n", i, argv[i]); + + printf(_("Your current working directory:\n%s%s\n"), + prefix ? "/" : "", prefix ? prefix : ""); + +---- + +Build and try it. 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 to the +function body: + +---- + const char *cfg_name; + +... + + git_config(git_default_config, NULL); + if (git_config_get_string_tmp("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_tmp()` 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" +---- + +NOTE: Again, the above is for sake of brevity in this tutorial. In a real change +you should not use `-m` but instead use the editor to write a meaningful +message. + +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 mimic 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. + +Be sure to include the header to allow you to use `struct wt_status`: +---- +#include "wt-status.h" +---- + +Then modify your `cmd_psuh` implementation to declare your `struct wt_status`, +prepare it, and print its contents: + +---- + struct wt_status status; + +... + + 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 add builtin/psuh.c +$ 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 includes: + +---- +#include "commit.h" +#include "pretty.h" +---- + +Then, add the following lines within your implementation of `cmd_psuh()` near +the declarations and the logic, respectively. + +---- + struct commit *c = NULL; + struct strbuf commitline = STRBUF_INIT; + +... + + 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 +pretty-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 add builtin/psuh.c +$ git commit -sm "psuh: display the top of origin/master" +---- + +[[add-documentation]] +=== 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. Try to use well-established manpage headers so your +documentation is consistent with other Git and UNIX manpages; this makes life +easier for your user, who can skip to the section they know contains the +information they need. + +NOTE: Before trying to build the docs, make sure you have the package `asciidoc` +installed. + +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 +---- + +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. + +[[add-usage]] +=== 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 array of usage +strings and a `builtin_psuh_options` array. + +Add a line to `#include "parse-options.h"`. + +At global scope, add your array of usage strings: + +---- +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 want to +explore `parse_options()` in more detail: + +---- + 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` parameter. It will strip the options you +specified in `options` from `argv` and the locations pointed to from `options` +entries will be updated. 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. + +Now that you have a usage hint, you can teach Git how to show it in the general +command list shown by `git help git` or `git help -a`, which is generated from +`command-list.txt`. Find the line for 'git-pull' so you can add your 'git-psuh' +line above it in alphabetical order. Now, we can add some attributes about the +command which impacts where it shows up in the aforementioned help commands. The +top of `command-list.txt` shares some information about what each attribute +means; in those help pages, the commands are sorted according to these +attributes. `git psuh` is user-facing, or porcelain - so we will mark it as +"mainporcelain". For "mainporcelain" commands, the comments at the top of +`command-list.txt` indicate we can also optionally add an attribute from another +list; since `git psuh` shows some information about the user's workspace but +doesn't modify anything, let's mark it as "info". Make sure to keep your +attributes in the same style as the rest of `command-list.txt` using spaces to +align and delineate them: + +---- +git-prune-packed plumbingmanipulators +git-psuh mainporcelain info +git-pull mainporcelain remote +git-push mainporcelain remote +---- + +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]] +== 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. Your +tests should: + +* Illustrate the current behavior of the feature +* Prove the current behavior matches the expected behavior +* Ensure the externally-visible behavior isn't broken in later changes + +So let's write some tests. + +Related reading: `t/README` + +[[overview-test-structure]] +=== Overview of Testing Structure + +The tests in Git live in `t/` and are named with a 4-digit decimal number using +the schema shown in the Naming Tests section of `t/README`. + +[[write-new-test]] +=== 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 a new file `t/t9999-psuh-tutorial.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. Let's make sure that `git psuh` doesn't exit poorly and does +mention the right animal somewhere: + +---- +test_expect_success 'runs correctly with no args and good output' ' + git psuh >actual && + grep Pony actual +' +---- + +Indicate that you've run everything you wanted by adding the following at the +bottom of your script: + +---- +test_done +---- + +Make sure you mark your test script executable: + +---- +$ chmod +x t/t9999-psuh-tutorial.sh +---- + +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. + +[[local-test]] +=== Running Locally + +Let's try and run locally: + +---- +$ make +$ cd t/ && prove t9999-psuh-tutorial.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 +---- + +NOTE: You can also do this with `make test` or use any testing harness which can +speak TAP. `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. + +[[ready-to-share]] +== Getting Ready to Share: Anatomy of a Patch Series + +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 contributions from +pull requests, and the patches emailed for review need to be formatted a +specific way. + +:patch-series: https://lore.kernel.org/git/pull.1218.git.git.1645209647.gitgitgadget@gmail.com/ +:lore: https://lore.kernel.org/git/ + +Before taking a look at how to convert your commits into emailed patches, +let's analyze what the end result, a "patch series", looks like. Here is an +{patch-series}[example] of the summary view for a patch series on the web interface of +the {lore}[Git mailing list archive]: + +---- +2022-02-18 18:40 [PATCH 0/3] libify reflog John Cai via GitGitGadget +2022-02-18 18:40 ` [PATCH 1/3] reflog: libify delete reflog function and helpers John Cai via GitGitGadget +2022-02-18 19:10 ` Ævar Arnfjörð Bjarmason [this message] +2022-02-18 19:39 ` Taylor Blau +2022-02-18 19:48 ` Ævar Arnfjörð Bjarmason +2022-02-18 19:35 ` Taylor Blau +2022-02-21 1:43 ` John Cai +2022-02-21 1:50 ` Taylor Blau +2022-02-23 19:50 ` John Cai +2022-02-18 20:00 ` // other replies elided +2022-02-18 18:40 ` [PATCH 2/3] reflog: call reflog_delete from reflog.c John Cai via GitGitGadget +2022-02-18 19:15 ` Ævar Arnfjörð Bjarmason +2022-02-18 20:26 ` Junio C Hamano +2022-02-18 18:40 ` [PATCH 3/3] stash: call reflog_delete from reflog.c John Cai via GitGitGadget +2022-02-18 19:20 ` Ævar Arnfjörð Bjarmason +2022-02-19 0:21 ` Taylor Blau +2022-02-22 2:36 ` John Cai +2022-02-22 10:51 ` Ævar Arnfjörð Bjarmason +2022-02-18 19:29 ` [PATCH 0/3] libify reflog Ævar Arnfjörð Bjarmason +2022-02-22 18:30 ` [PATCH v2 0/3] libify reflog John Cai via GitGitGadget +2022-02-22 18:30 ` [PATCH v2 1/3] stash: add test to ensure reflog --rewrite --updatref behavior John Cai via GitGitGadget +2022-02-23 8:54 ` Ævar Arnfjörð Bjarmason +2022-02-23 21:27 ` Junio C Hamano +// continued +---- + +We can note a few things: + +- Each commit is sent as a separate email, with the commit message title as + subject, prefixed with "[PATCH _i_/_n_]" for the _i_-th commit of an + _n_-commit series. +- Each patch is sent as a reply to an introductory email called the _cover + letter_ of the series, prefixed "[PATCH 0/_n_]". +- Subsequent iterations of the patch series are labelled "PATCH v2", "PATCH + v3", etc. in place of "PATCH". For example, "[PATCH v2 1/3]" would be the first of + three patches in the second iteration. Each iteration is sent with a new cover + letter (like "[PATCH v2 0/3]" above), itself a reply to the cover letter of the + previous iteration (more on that below). + +NOTE: A single-patch topic is sent with "[PATCH]", "[PATCH v2]", etc. without +_i_/_n_ numbering (in the above thread overview, no single-patch topic appears, +though). + +[[cover-letter]] +=== The cover letter + +In addition to an email per patch, the Git community also expects your patches +to come with a 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 +patches. + +The title of your cover letter should be something which succinctly covers the +purpose of your entire topic branch. It's often in the imperative mood, just +like our commit message titles. Here is how we'll title our series: + +--- +Add the 'psuh' command +--- + +The body of the cover letter is used to give additional context to reviewers. +Be sure to explain anything your patches don't make clear on their own, but +remember that since the cover letter is not recorded in the commit history, +anything that might be useful to future readers of the repository's history +should also be in your commit messages. + +Here's an example body for `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 tutorial and should not +be merged. +---- + +At this point the tutorial diverges, in order to demonstrate two +different methods of formatting your patchset and getting it reviewed. + +The first method to be covered is GitGitGadget, which is useful for those +already familiar with GitHub's common pull request workflow. This method +requires a GitHub account. + +The second method to be covered is `git send-email`, which can give slightly +more fine-grained control over the emails to be sent. This method requires some +setup which can change depending on your system and will not be covered in this +tutorial. + +Regardless of which method you choose, your engagement with reviewers will be +the same; the review process will be covered after the sections on GitGitGadget +and `git send-email`. + +[[howto-ggg]] +== Sending Patches via GitGitGadget + +One option for sending patches is to follow a typical pull request workflow and +send your patches out via 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 send them out for you. It also runs the Git continuous integration +suite for you. It's documented at https://gitgitgadget.github.io/. + +[[create-fork]] +=== Forking `git/git` on GitHub + +Before you can send your patch off to be reviewed using GitGitGadget, you will +need to fork the Git project and upload your changes. First thing - make sure +you have a GitHub account. + +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. + +[[upload-to-fork]] +=== 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 document, 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. + +[[send-pr-ggg]] +=== Sending a PR to GitGitGadget + +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 they're used by GitGitGadget +respectively as the subject and body of the cover letter for your change. Refer +to <> above for advice on how to title your +submission and what content to include in the description. + +NOTE: For single-patch contributions, your commit message should already be +meaningful and explain at a high level the purpose (what is happening and why) +of your patch, so you usually do not need any additional context. In that case, +remove the PR description that GitHub automatically generates from your commit +message (your PR description should be empty). If you do need to supply even +more context, you can do so in that space and it will be appended to the email +that GitGitGadget will send, between the three-dash line and the diffstat +(see <> for how this looks once +submitted). + +When you're happy, submit your pull request. + +[[run-ci-ggg]] +=== Running CI and Getting Ready to Send + +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 documentation, you just need someone who +already uses it to comment on your PR with `/allow `. GitGitGadget +will automatically run your PRs through the CI even without the permission given +but you will not be able to `/submit` your changes until someone allows you to +use the tool. + +NOTE: You can typically find someone who can `/allow` you on GitGitGadget by +either examining recent pull requests where someone has been granted `/allow` +(https://github.com/gitgitgadget/git/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+%22%2Fallow%22[Search: +is:pr is:open "/allow"]), in which case both the author and the person who +granted the `/allow` can now `/allow` you, or by inquiring on the +https://web.libera.chat/#git-devel[#git-devel] IRC channel on Libera Chat +linking your pull request and asking for someone to `/allow` you. + +If the CI fails, you can update your changes with `git 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-work-ggg]] +=== Check Your Work +//// + +[[send-mail-ggg]] +=== 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`. + +[[responding-ggg]] +=== Updating With Comments + +Skip ahead to <> for information on how to +reply to review comments you will receive on the mailing list. + +Once you have your branch again in the shape you want following all review +comments, you can submit again: + +---- +$ git push -f remotename psuh +---- + +Next, go look at your pull request against GitGitGadget; you should see the CI +has been kicked off again. Now while the CI is running is a good time for you +to modify your description at the top of the pull request thread; it will be +used again as the cover letter. You should use this space to describe what +has changed since your previous version, so that your reviewers have some idea +of what they're looking at. When the CI is done running, you can comment once +more with `/submit` - GitGitGadget will automatically add a v2 mark to your +changes. + +[[howto-git-send-email]] +== Sending Patches with `git send-email` + +If you don't want to use GitGitGadget, you can also use Git itself to mail your +patches. Some benefits of using Git this way include finer grained control of +subject line (for example, being able to use the tag [RFC PATCH] in the subject) +and being able to send a ``dry run'' mail to yourself to ensure it all looks +good before going out to the list. + +[[setup-git-send-email]] +=== 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 tutorial, 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. You will also need to +determine the right way to configure it to use your SMTP server; again, as this +configuration can change significantly based on your system and email setup, it +is out of scope for the context of this tutorial. + +[[format-patch]] +=== 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 --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 +normal way using `git rebase -i` or by adding a new commit than by modifying a +patch. + +NOTE: Optionally, you can also use the `--rfc` flag to prefix your patch subject +with ``[RFC PATCH]'' instead of ``[PATCH]''. RFC stands for ``request for +comments'' and indicates that while your code isn't quite ready for submission, +you'd like to begin the code review process. This can also be used when your +patch is a proposal, but you aren't sure whether the community wants to solve +the problem with that approach or not - to conduct a sort of design review. You +may also see on the list patches marked ``WIP'' - this means they are incomplete +but want reviewers to look at what they have so far. You can add this flag with +`--subject-prefix=WIP`. + +Check and make sure that your patches and cover letter template exist in the +directory you specified - you're nearly ready to send out your review! + +[[preparing-cover-letter]] +=== Preparing Email + +Since you invoked `format-patch` with `--cover-letter`, you've already got a +cover letter template ready. Open it up in your favorite editor. + +You should see a number of headers present already. Check that your `From:` +header is correct. Then modify your `Subject:` (see <> for +how to choose good title for your patch series): + +---- +Subject: [PATCH 0/7] Add the 'psuh' command +---- + +Make sure you retain the ``[PATCH 0/X]'' part; that's what indicates to the Git +community that this email is the beginning of a patch series, and many +reviewers filter their email for this type of flag. + +You'll need to add some extra parameters when you invoke `git send-email` to add +the cover letter. + +Next you'll have to fill out the body of your cover letter. Again, see +<> for what content to include. + +The template created by `git format-patch --cover-letter` includes a diffstat. +This gives reviewers a summary of what they're in for when reviewing your topic. +The one generated for `psuh` from the sample implementation looks like this: + +---- + Documentation/git-psuh.txt | 40 +++++++++++++++++++++ + Makefile | 1 + + builtin.h | 1 + + builtin/psuh.c | 73 ++++++++++++++++++++++++++++++++++++++ + git.c | 1 + + t/t9999-psuh-tutorial.sh | 12 +++++++ + 6 files changed, 128 insertions(+) + create mode 100644 Documentation/git-psuh.txt + create mode 100644 builtin/psuh.c + create mode 100755 t/t9999-psuh-tutorial.sh +---- + +Finally, the letter will include the version of Git used to generate the +patches. You can leave that string alone. + +[[sending-git-send-email]] +=== Sending Email + +At this point you should have a directory `psuh/` which is filled with your +patches and a cover letter. Time to mail it out! You can send it like this: + +---- +$ git send-email --to=target@example.com psuh/*.patch +---- + +NOTE: Check `git help send-email` for some other options which you may find +valuable, such as changing the Reply-to address or adding more CC and BCC lines. + +:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are + +not part of the core `git` binary and must be called directly. Clone the Git + +codebase and run `perl contrib/contacts/git-contacts`.] + +NOTE: If you're not sure whom to CC, running `contrib/contacts/git-contacts` can +list potential reviewers. In addition, you can do `git send-email +--cc-cmd='perl contrib/contacts/git-contacts' feature/*.patch`{contrib-scripts} to +automatically pass this list of emails to `send-email`. + +NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but +please don't send your patchset from the tutorial to the real mailing list! For +now, you can send it to yourself, to make sure you understand how it will look. + +After you run the command above, 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 be sent! Congratulations! + +Awesome, now the community will drop everything and review your changes. (Just +kidding - be patient!) + +[[v2-git-send-email]] +=== Sending v2 + +This section will focus on how to send a v2 of your patchset. To learn what +should go into v2, skip ahead to <> for +information on how to handle comments from reviewers. + +We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll +mark the tip of our v1 branch for easy reference: + +---- +$ git checkout psuh +$ git branch psuh-v1 +---- + +Refine your patch series by using `git rebase -i` to adjust commits based upon +reviewer comments. Once the patch series is ready for submission, generate your +patches again, but with some new flags: + +---- +$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master.. +---- + +The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a +range-diff between `psuh-v1` and `psuh` in the cover letter (see +linkgit:git-range-diff[1]). This helps tell reviewers about the differences +between your v1 and v2 patches. + +The `-v2` parameter tells `format-patch` to output your patches +as version "2". For instance, you may notice that your v2 patches are +all named like `v2-000n-my-commit-subject.patch`. `-v2` will also format +your patches by prefixing them with "[PATCH v2]" instead of "[PATCH]", +and your range-diff will be prefaced with "Range-diff against v1". + +After you run this command, `format-patch` will output the patches to the `psuh/` +directory, alongside the v1 patches. Using a single directory makes it easy to +refer to the old v1 patches while proofreading the v2 patches, but you will need +to be careful to send out only the v2 patches. We will use a pattern like +`psuh/v2-*.patch` (not `psuh/*.patch`, which would match v1 and v2 patches). + +Edit your cover letter again. Now is a good time to mention what's different +between your last version and now, if it's something significant. You do not +need the exact same body in your second cover letter; focus on explaining to +reviewers the changes you've made that may not be as visible. + +You will also need to go and find the Message-ID of your previous cover letter. +You can either note it when you send the first series, from the output of `git +send-email`, or you can look it up on the +https://lore.kernel.org/git[mailing list]. Find your cover letter in the +archives, click on it, then click "permalink" or "raw" to reveal the Message-ID +header. It should match: + +---- +Message-ID: +---- + +Your Message-ID is ``. This example will be used +below as well; make sure to replace it with the correct Message-ID for your +**previous cover letter** - that is, if you're sending v2, use the Message-ID +from v1; if you're sending v3, use the Message-ID from v2. + +While you're looking at the email, you should also note who is CC'd, as it's +common practice in the mailing list to keep all CCs on a thread. You can add +these CC lines directly to your cover letter with a line like so in the header +(before the Subject line): + +---- +CC: author@example.com, Othe R +---- + +Now send the emails again, paying close attention to which messages you pass in +to the command: + +---- +$ git send-email --to=target@example.com + --in-reply-to="" + psuh/v2-*.patch +---- + +[[single-patch]] +=== Bonus Chapter: One-Patch Changes + +In some cases, your very small change may consist of only one patch. When that +happens, you only need to send one email. Your commit message should already be +meaningful and explain at a high level the purpose (what is happening and why) +of your patch, but if you need to supply even more context, you can do so below +the `---` in your patch. Take the example below, which was generated with `git +format-patch` on a single commit, and then edited to add the content between +the `---` and the diffstat. + +---- +From 1345bbb3f7ac74abde040c12e737204689a72723 Mon Sep 17 00:00:00 2001 +From: A U Thor +Date: Thu, 18 Apr 2019 15:11:02 -0700 +Subject: [PATCH] README: change the grammar + +I think it looks better this way. This part of the commit message will +end up in the commit-log. + +Signed-off-by: A U Thor +--- +Let's have a wild discussion about grammar on the mailing list. This +part of my email will never end up in the commit log. Here is where I +can add additional context to the mailing list about my intent, outside +of the context of the commit log. This section was added after `git +format-patch` was run, by editing the patch file in a text editor. + + README.md | 2 +- + 1 file changed, 1 insertion(+), 1 deletion(-) + +diff --git a/README.md b/README.md +index 88f126184c..38da593a60 100644 +--- a/README.md ++++ b/README.md +@@ -3,7 +3,7 @@ + Git - fast, scalable, distributed revision control system + ========================================================= + +-Git is a fast, scalable, distributed revision control system with an ++Git is a fast, scalable, and distributed revision control system with an + unusually rich command set that provides both high-level operations + and full access to internals. + +-- +2.21.0.392.gf8f6787159e-goog +---- + +[[now-what]] +== My Patch Got Emailed - Now What? + +Please give reviewers enough time to process your initial patch before +sending an updated version. That is, resist the temptation to send a new +version immediately, because others may have already started reviewing +your initial version. + +While waiting for review comments, you may find mistakes in your initial +patch, or perhaps realize a different and better way to achieve the goal +of the patch. In this case you may communicate your findings to other +reviewers as follows: + + - If the mistakes you found are minor, send a reply to your patch as if + you were a reviewer and mention that you will fix them in an + updated version. + + - On the other hand, if you think you want to change the course so + drastically that reviews on the initial patch would be a waste of + time (for everyone involved), retract the patch immediately with + a reply like "I am working on a much better approach, so please + ignore this patch and wait for the updated version." + +Now, the above is a good practice if you sent your initial patch +prematurely without polish. But a better approach of course is to avoid +sending your patch prematurely in the first place. + +Please be considerate of the time needed by reviewers to examine each +new version of your patch. Rather than seeing the initial version right +now (followed by several "oops, I like this version better than the +previous one" patches over 2 days), reviewers would strongly prefer if a +single polished version came 2 days later instead, and that version with +fewer mistakes were the only one they would need to review. + + +[[reviewing]] +=== Responding to Reviews + +After a few days, you will hopefully receive a reply to your patchset with some +comments. Woohoo! Now you can get back to work. + +It's good manners to reply to each comment, notifying the reviewer that you have +made the change suggested, feel the original is better, or that the comment +inspired you to do something a new way which is superior to both the original +and the suggested change. This way reviewers don't need to inspect your v2 to +figure out whether you implemented their comment or not. + +Reviewers may ask you about what you wrote in the patchset, either in +the proposed commit log message or in the changes themselves. You +should answer these questions in your response messages, but often the +reason why reviewers asked these questions to understand what you meant +to write is because your patchset needed clarification to be understood. + +Do not be satisfied by just answering their questions in your response +and hear them say that they now understand what you wanted to say. +Update your patches to clarify the points reviewers had trouble with, +and prepare your v2; the words you used to explain your v1 to answer +reviewers' questions may be useful thing to use. Your goal is to make +your v2 clear enough so that it becomes unnecessary for you to give the +same explanation to the next person who reads it. + +If you are going to push back on a comment, be polite and explain why you feel +your original is better; be prepared that the reviewer may still disagree with +you, and the rest of the community may weigh in on one side or the other. As +with all code reviews, it's important to keep an open mind to doing something a +different way than you originally planned; other reviewers have a different +perspective on the project than you do, and may be thinking of a valid side +effect which had not occurred to you. It is always okay to ask for clarification +if you aren't sure why a change was suggested, or what the reviewer is asking +you to do. + +Make sure your email client has a plaintext email mode and it is turned on; 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. + +When you're making changes to your code, it is cleanest - that is, the resulting +commits are easiest to look at - if you use `git rebase -i` (interactive +rebase). Take a look at this +https://www.oreilly.com/library/view/git-pocket-guide/9781449327507/ch10.html[overview] +from O'Reilly. The general idea is to modify each commit which requires changes; +this way, instead of having a patch A with a mistake, a patch B which was fine +and required no upstream reviews in v1, and a patch C which fixes patch A for +v2, you can just ship a v2 with a correct patch A and correct patch B. This is +changing history, but since it's local history which you haven't shared with +anyone, that is okay for now! (Later, it may not make sense to do this; take a +look at the section below this one for some context.) + +[[after-approval]] +=== After Review Approval + +The Git project has four integration branches: `seen`, `next`, `master`, and +`maint`. Your change will be placed into `seen` 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 merge your topic branch to `next` and life is good. + +However, if you discover it isn't so perfect after this point, you may need to +take some special steps depending on where you are in the process. + +If the maintainer has announced in the "What's cooking in git.git" email that +your topic is marked for `next` - that is, that they plan to merge it to `next` +but have not yet done so - you should send an email asking the maintainer to +wait a little longer: "I've sent v4 of my series and you marked it for `next`, +but I need to change this and that - please wait for v5 before you merge it." + +If the topic has already been merged to `next`, rather than modifying your +patches with `git rebase -i`, you should make further changes incrementally - +that is, with another commit, based on top of the maintainer's topic branch as +detailed in https://github.com/gitster/git. Your work is still in the same topic +but is now incremental, rather than a wholesale rewrite of the topic branch. + +The topic branches in the maintainer's GitHub are mirrored in GitGitGadget, so +if you're sending your reviews out that way, you should be sure to open your PR +against the appropriate GitGitGadget/Git branch. + +If you're using `git send-email`, you can use it the same way as before, but you +should generate your diffs from `..` and base your work on +`` instead of `master`. diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt new file mode 100644 index 00000000000000..dec8afe5b10533 --- /dev/null +++ b/Documentation/MyFirstObjectWalk.txt @@ -0,0 +1,898 @@ += My First Object Walk + +== What's an Object Walk? + +The object walk is a key concept in Git - this is the process that underpins +operations like object transfer and fsck. Beginning from a given commit, the +list of objects is found by walking parent relationships between commits (commit +X based on commit W) and containment relationships between objects (tree Y is +contained within commit X, and blob Z is located within tree Y, giving our +working tree for commit X something like `y/z.txt`). + +A related concept is the revision walk, which is focused on commit objects and +their parent relationships and does not delve into other object types. The +revision walk is used for operations like `git log`. + +=== Related Reading + +- `Documentation/user-manual.txt` under "Hacking Git" contains some coverage of + the revision walker in its various incarnations. +- `revision.h` +- https://eagain.net/articles/git-for-computer-scientists/[Git for Computer Scientists] + gives a good overview of the types of objects in Git and what your object + walk is really describing. + +== Setting Up + +Create a new branch from `master`. + +---- +git checkout -b revwalk origin/master +---- + +We'll put our fiddling into a new command. For fun, let's name it `git walken`. +Open up a new file `builtin/walken.c` and set up the command handler: + +---- +/* + * "git walken" + * + * Part of the "My First Object Walk" tutorial. + */ + +#include "builtin.h" +#include "trace.h" + +int cmd_walken(int argc, const char **argv, const char *prefix) +{ + trace_printf(_("cmd_walken incoming...\n")); + return 0; +} +---- + +NOTE: `trace_printf()`, defined in `trace.h`, differs from `printf()` in +that it can be turned on or off at runtime. For the purposes of this +tutorial, we will write `walken` as though it is intended for use as +a "plumbing" command: that is, a command which is used primarily in +scripts, rather than interactively by humans (a "porcelain" command). +So we will send our debug output to `trace_printf()` instead. +When 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() + }; + + argc = parse_options(argc, argv, prefix, options, walken_usage, 0); + + ... +} +---- + +Also add the relevant line in `builtin.h` near `cmd_whatchanged()`: + +---- +int cmd_walken(int argc, const char **argv, const char *prefix); +---- + +Include the command in `git.c` in `commands[]` near the entry for `whatchanged`, +maintaining alphabetical ordering: + +---- +{ "walken", cmd_walken, RUN_SETUP }, +---- + +Add it to the `Makefile` near the line for `builtin/worktree.o`: + +---- +BUILTIN_OBJS += builtin/walken.o +---- + +Build and test out your command, without forgetting to ensure the `DEVELOPER` +flag is set, and with `GIT_TRACE` enabled so the debug output can be seen: + +---- +$ echo DEVELOPER=1 >>config.mak +$ make +$ GIT_TRACE=1 ./bin-wrappers/git walken +---- + +NOTE: For a more exhaustive overview of the new command process, take a look at +`Documentation/MyFirstContribution.txt`. + +NOTE: A reference implementation can be found at +https://github.com/nasamuffin/git/tree/revwalk. + +=== `struct rev_cmdline_info` + +The definition of `struct rev_cmdline_info` can be found in `revision.h`. + +This struct is contained within the `rev_info` struct and is used to reflect +parameters provided by the user over the CLI. + +`nr` represents the number of `rev_cmdline_entry` present in the array. + +`alloc` is used by the `ALLOC_GROW` macro. Check `alloc.h` - this variable is +used to track the allocated size of the list. + +Per entry, we find: + +`item` is the object provided upon which to base the object walk. Items in Git +can be blobs, trees, commits, or tags. (See `Documentation/gittutorial-2.txt`.) + +`name` is the object ID (OID) of the object - a hex string you may be familiar +with from using Git to organize your source in the past. Check the tutorial +mentioned above towards the top for a discussion of where the OID can come +from. + +`whence` indicates some information about what to do with the parents of the +specified object. We'll explore this flag more later on; take a look at +`Documentation/revisions.txt` to get an idea of what could set the `whence` +value. + +`flags` are used to hint the beginning of the revision walk and are the first +block under the `#include`s in `revision.h`. The most likely ones to be set in +the `rev_cmdline_info` are `UNINTERESTING` and `BOTTOM`, but these same flags +can be used during the walk, as well. + +=== `struct rev_info` + +This one is quite a bit longer, and many fields are only used during the walk +by `revision.c` - not configuration options. Most of the configurable flags in +`struct rev_info` have a mirror in `Documentation/rev-list-options.txt`. It's a +good idea to take some time and read through that document. + +== Basic Commit Walk + +First, let's see if we can replicate the output of `git log --oneline`. We'll +refer back to the implementation frequently to discover norms when performing +an object walk of our own. + +To do so, we'll first find all the commits, in order, which preceded the current +commit. We'll extract the name and subject of the commit from each. + +Ideally, we will also be able to find out which ones are currently at the tip of +various branches. + +=== Setting Up + +Preparing for your object walk has some distinct stages. + +1. Perform default setup for this mode, and others which may be invoked. +2. Check configuration files for relevant settings. +3. Set up the `rev_info` struct. +4. Tweak the initialized `rev_info` to suit the current walk. +5. Prepare the `rev_info` for the walk. +6. Iterate over the objects, processing each one. + +==== Default Setups + +Before examining configuration files which may modify command behavior, set up +default state for switches or options your command may have. If your command +utilizes other Git components, ask them to set up their default states as well. +For instance, `git log` takes advantage of `grep` and `diff` functionality, so +its `init_log_defaults()` sets its own state (`decoration_style`) and asks +`grep` and `diff` to initialize themselves by calling each of their +initialization functions. + +==== Configuring From `.gitconfig` + +Next, we should have a look at any relevant configuration settings (i.e., +settings readable and settable from `git config`). This is done by providing a +callback to `git_config()`; within that callback, you can also invoke methods +from other components you may need that need to intercept these options. Your +callback will be invoked once per each configuration value which Git knows about +(global, local, worktree, etc.). + +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`. +We'll also need to include the `config.h` header: + +---- +#include "config.h" + +... + +static int git_walken_config(const char *var, const char *value, + const struct config_context *ctx, void *cb) +{ + /* + * For now, we don't have any custom configuration, so fall back to + * the default config. + */ + return git_default_config(var, value, ctx, cb); +} +---- + +Make sure to invoke `git_config()` with it in your `cmd_walken()`: + +---- +int cmd_walken(int argc, const char **argv, const char *prefix) +{ + ... + + git_config(git_walken_config, NULL); + + ... +} +---- + +==== Setting Up `rev_info` + +Now that we've gathered external configuration and options, it's time to +initialize the `rev_info` object which we will use to perform the walk. This is +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. +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.*/ + struct rev_info rev; + ... + + /* This should go after the git_config() call. */ + repo_init_revisions(the_repository, &rev, prefix); + + ... +} +---- + +==== Tweaking `rev_info` For the Walk + +We're getting close, but we're still not quite ready to go. Now that `rev` is +initialized, we can modify it to fit our needs. This is usually done within a +helper for clarity, so let's add one: + +---- +static void final_rev_info_setup(struct rev_info *rev) +{ + /* + * We want to mimic the appearance of `git log --oneline`, so let's + * force oneline format. + */ + get_commit_format("oneline", rev); + + /* Start our object walk at HEAD. */ + add_head_to_pending(rev); +} +---- + +[NOTE] +==== +Instead of using the shorthand `add_head_to_pending()`, you could do +something like this: +---- + struct setup_revision_opt opt; + + memset(&opt, 0, sizeof(opt)); + opt.def = "HEAD"; + opt.revarg_opt = REVARG_COMMITTISH; + setup_revisions(argc, argv, rev, &opt); +---- +Using a `setup_revision_opt` gives you finer control over your walk's starting +point. +==== + +Then let's invoke `final_rev_info_setup()` after the call to +`repo_init_revisions()`: + +---- +int cmd_walken(int argc, const char **argv, const char *prefix) +{ + ... + + final_rev_info_setup(&rev); + + ... +} +---- + +Later, we may wish to add more arguments to `final_rev_info_setup()`. But for +now, this is all we need. + +==== Preparing `rev_info` For the Walk + +Now that `rev` is all initialized and configured, we've got one more setup step +before we get rolling. We can do this in a helper, which will both prepare the +`rev_info` for the walk, and perform the walk itself. Let's start the helper +with the call to `prepare_revision_walk()`, which can return an error without +dying on its own: + +---- +static void walken_commit_walk(struct rev_info *rev) +{ + if (prepare_revision_walk(rev)) + die(_("revision walk setup failed")); +} +---- + +NOTE: `die()` prints to `stderr` and exits the program. Since it will print to +`stderr` it's likely to be seen by a human, so we will localize it. + +==== Performing the Walk! + +Finally! We are ready to begin the walk itself. Now we can see that `rev_info` +can also be used as an iterator; we move to the next item in the walk by using +`get_revision()` repeatedly. Add the listed variable declarations at the top and +the walk loop below the `prepare_revision_walk()` call within your +`walken_commit_walk()`: + +---- +#include "pretty.h" + +... + +static void walken_commit_walk(struct rev_info *rev) +{ + struct commit *commit; + struct strbuf prettybuf = STRBUF_INIT; + + ... + + while ((commit = get_revision(rev))) { + strbuf_reset(&prettybuf); + pp_commit_easy(CMIT_FMT_ONELINE, commit, &prettybuf); + puts(prettybuf.buf); + } + strbuf_release(&prettybuf); +} +---- + +NOTE: `puts()` prints a `char*` to `stdout`. Since this is the part of the +command we expect to be machine-parsed, we're sending it directly to stdout. + +Give it a shot. + +---- +$ make +$ ./bin-wrappers/git walken +---- + +You should see all of the subject lines of all the commits in +your tree's history, in order, ending with the initial commit, "Initial revision +of "git", the information manager from hell". Congratulations! You've written +your first revision walk. You can play with printing some additional fields +from each commit if you're curious; have a look at the functions available in +`commit.h`. + +=== Adding a Filter + +Next, let's try to filter the commits we see based on their author. This is +equivalent to running `git log --author=`. We can add a filter by +modifying `rev_info.grep_filter`, which is a `struct grep_opt`. + +First some setup. Add `grep_config()` to `git_walken_config()`: + +---- +static int git_walken_config(const char *var, const char *value, + const struct config_context *ctx, void *cb) +{ + grep_config(var, value, ctx, cb); + return git_default_config(var, value, ctx, cb); +} +---- + +Next, we can modify the `grep_filter`. This is done with convenience functions +found in `grep.h`. For fun, we're filtering to only commits from folks using a +`gmail.com` email address - a not-very-precise guess at who may be working on +Git as a hobby. Since we're checking the author, which is a specific line in the +header, we'll use the `append_header_grep_pattern()` helper. We can use +the `enum grep_header_field` to indicate which part of the commit header we want +to search. + +In `final_rev_info_setup()`, add your filter line: + +---- +static void final_rev_info_setup(int argc, const char **argv, + const char *prefix, struct rev_info *rev) +{ + ... + + append_header_grep_pattern(&rev->grep_filter, GREP_HEADER_AUTHOR, + "gmail"); + compile_grep_patterns(&rev->grep_filter); + + ... +} +---- + +`append_header_grep_pattern()` adds your new "gmail" pattern to `rev_info`, but +it won't work unless we compile it with `compile_grep_patterns()`. + +NOTE: If you are using `setup_revisions()` (for example, if you are passing a +`setup_revision_opt` instead of using `add_head_to_pending()`), you don't need +to call `compile_grep_patterns()` because `setup_revisions()` calls it for you. + +NOTE: We could add the same filter via the `append_grep_pattern()` helper if we +wanted to, but `append_header_grep_pattern()` adds the `enum grep_context` and +`enum grep_pat_token` for us. + +=== Changing the Order + +There are a few ways that we can change the order of the commits during a +revision walk. Firstly, we can use the `enum rev_sort_order` to choose from some +typical orderings. + +`topo_order` is the same as `git log --topo-order`: we avoid showing a parent +before all of its children have been shown, and we avoid mixing commits which +are in different lines of history. (`git help log`'s section on `--topo-order` +has a very nice diagram to illustrate this.) + +Let's see what happens when we run with `REV_SORT_BY_COMMIT_DATE` as opposed to +`REV_SORT_BY_AUTHOR_DATE`. Add the following: + +---- +static void final_rev_info_setup(int argc, const char **argv, + const char *prefix, struct rev_info *rev) +{ + ... + + rev->topo_order = 1; + rev->sort_order = REV_SORT_BY_COMMIT_DATE; + + ... +} +---- + +Let's output this into a file so we can easily diff it with the walk sorted by +author date. + +---- +$ make +$ ./bin-wrappers/git walken > commit-date.txt +---- + +Then, let's sort by author date and run it again. + +---- +static void final_rev_info_setup(int argc, const char **argv, + const char *prefix, struct rev_info *rev) +{ + ... + + rev->topo_order = 1; + rev->sort_order = REV_SORT_BY_AUTHOR_DATE; + + ... +} +---- + +---- +$ make +$ ./bin-wrappers/git walken > author-date.txt +---- + +Finally, compare the two. This is a little less helpful without object names or +dates, but hopefully we get the idea. + +---- +$ diff -u commit-date.txt author-date.txt +---- + +This display indicates that commits can be reordered after they're written, for +example with `git rebase`. + +Let's try one more reordering of commits. `rev_info` exposes a `reverse` flag. +Set that flag somewhere inside of `final_rev_info_setup()`: + +---- +static void final_rev_info_setup(int argc, const char **argv, const char *prefix, + struct rev_info *rev) +{ + ... + + rev->reverse = 1; + + ... +} +---- + +Run your walk again and note the difference in order. (If you remove the grep +pattern, you should see the last commit this call gives you as your current +HEAD.) + +== Basic Object Walk + +So far we've been walking only commits. But Git has more types of objects than +that! Let's see if we can walk _all_ objects, and find out some information +about each one. + +We can base our work on an example. `git pack-objects` prepares all kinds of +objects for packing into a bitmap or packfile. The work we are interested in +resides in `builtin/pack-objects.c:get_object_list()`; examination of that +function shows that the all-object walk is being performed by +`traverse_commit_list()` or `traverse_commit_list_filtered()`. Those two +functions reside in `list-objects.c`; examining the source shows that, despite +the name, these functions traverse all kinds of objects. Let's have a look at +the arguments to `traverse_commit_list()`. + +- `struct rev_info *revs`: This is the `rev_info` used for the walk. If + its `filter` member is not `NULL`, then `filter` contains information for + how to filter the object list. +- `show_commit_fn show_commit`: A callback which will be used to handle each + individual commit object. +- `show_object_fn show_object`: A callback which will be used to handle each + non-commit object (so each blob, tree, or tag). +- `void *show_data`: A context buffer which is passed in turn to `show_commit` + and `show_object`. + +In addition, `traverse_commit_list_filtered()` has an additional parameter: + +- `struct oidset *omitted`: A linked-list of object IDs which the provided + filter caused to be omitted. + +It looks like these methods use callbacks we provide instead of needing us +to call it repeatedly ourselves. Cool! Let's add the callbacks first. + +For the sake of this tutorial, we'll simply keep track of how many of each kind +of object we find. At file scope in `builtin/walken.c` add the following +tracking variables: + +---- +static int commit_count; +static int tag_count; +static int blob_count; +static int tree_count; +---- + +Commits are handled by a different callback than other objects; let's do that +one first: + +---- +static void walken_show_commit(struct commit *cmt, void *buf) +{ + commit_count++; +} +---- + +The `cmt` argument is fairly self-explanatory. But it's worth mentioning that +the `buf` argument is actually the context buffer that we can provide to the +traversal calls - `show_data`, which we mentioned a moment ago. + +Since we have the `struct commit` object, we can look at all the same parts that +we looked at in our earlier commit-only walk. For the sake of this tutorial, +though, we'll just increment the commit counter and move on. + +The callback for non-commits is a little different, as we'll need to check +which kind of object we're dealing with: + +---- +static void walken_show_object(struct object *obj, const char *str, void *buf) +{ + switch (obj->type) { + case OBJ_TREE: + tree_count++; + break; + case OBJ_BLOB: + blob_count++; + break; + case OBJ_TAG: + tag_count++; + break; + case OBJ_COMMIT: + BUG("unexpected commit object in walken_show_object\n"); + default: + BUG("unexpected object type %s in walken_show_object\n", + type_name(obj->type)); + } +} +---- + +Again, `obj` is fairly self-explanatory, and we can guess that `buf` is the same +context pointer that `walken_show_commit()` receives: the `show_data` argument +to `traverse_commit_list()` and `traverse_commit_list_filtered()`. Finally, +`str` contains the name of the object, which ends up being something like +`foo.txt` (blob), `bar/baz` (tree), or `v1.2.3` (tag). + +To help assure us that we aren't double-counting commits, we'll include some +complaining if a commit object is routed through our non-commit callback; we'll +also complain if we see an invalid object type. Since those two cases should be +unreachable, and would only change in the event of a semantic change to the Git +codebase, we complain by using `BUG()` - which is a signal to a developer that +the change they made caused unintended consequences, and the rest of the +codebase needs to be updated to understand that change. `BUG()` is not intended +to be seen by the public, so it is not localized. + +Our main object walk implementation is substantially different from our commit +walk implementation, so let's make a new function to perform the object walk. We +can perform setup which is applicable to all objects here, too, to keep separate +from setup which is applicable to commit-only walks. + +We'll start by enabling all types of objects in the `struct rev_info`. We'll +also turn on `tree_blobs_in_commit_order`, which means that we will walk a +commit's tree and everything it points to immediately after we find each commit, +as opposed to waiting for the end and walking through all trees after the commit +history has been discovered. With the appropriate settings configured, we are +ready to call `prepare_revision_walk()`. + +---- +static void walken_object_walk(struct rev_info *rev) +{ + rev->tree_objects = 1; + rev->blob_objects = 1; + rev->tag_objects = 1; + rev->tree_blobs_in_commit_order = 1; + + if (prepare_revision_walk(rev)) + die(_("revision walk setup failed")); + + commit_count = 0; + tag_count = 0; + blob_count = 0; + tree_count = 0; +---- + +Let's start by calling just the unfiltered walk and reporting our counts. +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, + blob_count, tag_count, tree_count); +} +---- + +NOTE: This output is intended to be machine-parsed. Therefore, we are not +sending it to `trace_printf()`, and we are not localizing it - we need scripts +to be able to count on the formatting to be exactly the way it is shown here. +If we were intending this output to be read by humans, we would need to localize +it with `_()`. + +Finally, we'll ask `cmd_walken()` to use the object walk instead. Discussing +command line options is out of scope for this tutorial, so we'll just hardcode +a branch we can change at compile time. Where you call `final_rev_info_setup()` +and `walken_commit_walk()`, instead branch like so: + +---- + if (1) { + add_head_to_pending(&rev); + walken_object_walk(&rev); + } else { + final_rev_info_setup(argc, argv, prefix, &rev); + walken_commit_walk(&rev); + } +---- + +NOTE: For simplicity, we've avoided all the filters and sorts we applied in +`final_rev_info_setup()` and simply added `HEAD` to our pending queue. If you +want, you can certainly use the filters we added before by moving +`final_rev_info_setup()` out of the conditional and removing the call to +`add_head_to_pending()`. + +Now we can try to run our command! It should take noticeably longer than the +commit walk, but an examination of the output will give you an idea why. Your +output should look similar to this example, but with different counts: + +---- +Object walk completed. Found 55733 commits, 100274 blobs, 0 tags, and 104210 trees. +---- + +This makes sense. We have more trees than commits because the Git project has +lots of subdirectories which can change, plus at least one tree per commit. We +have no tags because we started on a commit (`HEAD`) and while tags can point to +commits, commits can't point to tags. + +NOTE: You will have different counts when you run this yourself! The number of +objects grows along with the Git project. + +=== Adding a Filter + +There are a handful of filters that we can apply to the object walk laid out in +`Documentation/rev-list-options.txt`. These filters are typically useful for +operations such as creating packfiles or performing a partial clone. They are +defined in `list-objects-filter-options.h`. For the purposes of this tutorial we +will use the "tree:1" filter, which causes the walk to omit all trees and blobs +which are not directly referenced by commits reachable from the commit in +`pending` when the walk begins. (`pending` is the list of objects which need to +be traversed during a walk; you can imagine a breadth-first tree traversal to +help understand. In our case, that means we omit trees and blobs not directly +referenced by `HEAD` or `HEAD`'s history, because we begin the walk with only +`HEAD` in the `pending` list.) + +For now, we are not going to track the omitted objects, so we'll replace those +parameters with `NULL`. For the sake of simplicity, we'll add a simple +build-time branch to use our filter or not. Preface the line calling +`traverse_commit_list()` with the following, which will remind us which kind of +walk we've just performed: + +---- + if (0) { + /* Unfiltered: */ + trace_printf(_("Unfiltered object walk.\n")); + } else { + trace_printf( + _("Filtered object walk with filterspec 'tree:1'.\n")); + + parse_list_objects_filter(&rev->filter, "tree:1"); + } + traverse_commit_list(rev, walken_show_commit, + walken_show_object, NULL); +---- + +The `rev->filter` member is usually built directly from a command +line argument, so the module provides an easy way to build one from a string. +Even though we aren't taking user input right now, we can still build one with +a hardcoded string using `parse_list_objects_filter()`. + +With the filter spec "tree:1", we are expecting to see _only_ the root tree for +each commit; therefore, the tree object count should be less than or equal to +the number of commits. (For an example of why that's true: `git commit --revert` +points to the same tree object as its grandparent.) + +=== Counting Omitted Objects + +We also have the capability to enumerate all objects which were omitted by a +filter, like with `git log --filter= --filter-print-omitted`. To do this, +change `traverse_commit_list()` to `traverse_commit_list_filtered()`, which is +able to populate an `omitted` list. Asking for this list of filtered objects +may cause performance degradations, however, because in this case, despite +filtering objects, the possibly much larger set of all reachable objects must +be processed in order to populate that list. + +First, add the `struct oidset` and related items we will use to iterate it: + +---- +#include "oidset.h" + +... + +static void walken_object_walk( + ... + + struct oidset omitted; + struct oidset_iter oit; + struct object_id *oid = NULL; + int omitted_count = 0; + oidset_init(&omitted, 0); + + ... +---- + +Replace the call to `traverse_commit_list()` with +`traverse_commit_list_filtered()` and pass a pointer to the `omitted` oidset +defined and initialized above: + +---- + ... + + traverse_commit_list_filtered(rev, + walken_show_commit, walken_show_object, NULL, &omitted); + + ... +---- + +Then, after your traversal, the `oidset` traversal is pretty straightforward. +Count all the objects within and modify the print statement: + +---- + /* Count the omitted objects. */ + oidset_iter_init(&omitted, &oit); + + while ((oid = oidset_iter_next(&oit))) + omitted_count++; + + printf("commits %d\nblobs %d\ntags %d\ntrees %d\nomitted %d\n", + commit_count, blob_count, tag_count, tree_count, omitted_count); +---- + +By running your walk with and without the filter, you should find that the total +object count in each case is identical. You can also time each invocation of +the `walken` subcommand, with and without `omitted` being passed in, to confirm +to yourself the runtime impact of tracking all omitted objects. + +=== Changing the Order + +Finally, let's demonstrate that you can also reorder walks of all objects, not +just walks of commits. First, we'll make our handlers chattier - modify +`walken_show_commit()` and `walken_show_object()` to print the object as they +go: + +---- +#include "hex.h" + +... + +static void walken_show_commit(struct commit *cmt, void *buf) +{ + trace_printf("commit: %s\n", oid_to_hex(&cmt->object.oid)); + commit_count++; +} + +static void walken_show_object(struct object *obj, const char *str, void *buf) +{ + trace_printf("%s: %s\n", type_name(obj->type), oid_to_hex(&obj->oid)); + + ... +} +---- + +NOTE: Since we will be examining this output directly as humans, we'll use +`trace_printf()` here. Additionally, since this change introduces a significant +number of printed lines, using `trace_printf()` will allow us to easily silence +those lines without having to recompile. + +(Leave the counter increment logic in place.) + +With only that change, run again (but save yourself some scrollback): + +---- +$ GIT_TRACE=1 ./bin-wrappers/git walken 2>&1 | head -n 10 +---- + +Take a look at the top commit with `git show` and the object ID you printed; it +should be the same as the output of `git show HEAD`. + +Next, let's change a setting on our `struct rev_info` within +`walken_object_walk()`. Find where you're changing the other settings on `rev`, +such as `rev->tree_objects` and `rev->tree_blobs_in_commit_order`, and add the +`reverse` setting at the bottom: + +---- + ... + + rev->tree_objects = 1; + rev->blob_objects = 1; + rev->tag_objects = 1; + rev->tree_blobs_in_commit_order = 1; + rev->reverse = 1; + + ... +---- + +Now, run again, but this time, let's grab the last handful of objects instead +of the first handful: + +---- +$ make +$ GIT_TRACE=1 ./bin-wrappers/git walken 2>&1 | tail -n 10 +---- + +The last commit object given should have the same OID as the one we saw at the +top before, and running `git show ` with that OID should give you again +the same results as `git show HEAD`. Furthermore, if you run and examine the +first ten lines again (with `head` instead of `tail` like we did before applying +the `reverse` setting), you should see that now the first commit printed is the +initial commit, `e83c5163`. + +== Wrapping Up + +Let's review. In this tutorial, we: + +- Built a commit walk from the ground up +- Enabled a grep filter for that commit walk +- Changed the sort order of that filtered commit walk +- Built an object walk (tags, commits, trees, and blobs) from the ground up +- Learned how to add a filter-spec to an object walk +- Changed the display order of the filtered object walk diff --git a/Documentation/RelNotes/1.5.0.txt b/Documentation/RelNotes/1.5.0.txt index daf4bdb0d7bb24..d6d42f31835889 100644 --- a/Documentation/RelNotes/1.5.0.txt +++ b/Documentation/RelNotes/1.5.0.txt @@ -251,7 +251,7 @@ Updates in v1.5.0 since v1.4.4 series the repository when that happens. -* Crufts removal +* Cruft removal - We used to say "old commits are retrievable using reflog and 'master@{yesterday}' syntax as long as you haven't run @@ -379,7 +379,7 @@ Updates in v1.5.0 since v1.4.4 series - The value of i18n.commitencoding in the originating repository is recorded in the commit object on the "encoding" header, if it is not UTF-8. git-log and friends notice this, - and reencodes the message to the log output encoding when + and re-encodes the message to the log output encoding when displaying, if they are different. The log output encoding is determined by "git log --encoding=", i18n.logoutputencoding configuration, or i18n.commitencoding diff --git a/Documentation/RelNotes/1.6.0.3.txt b/Documentation/RelNotes/1.6.0.3.txt index ae0577836ae8b3..ad36c0f0b7c6e5 100644 --- a/Documentation/RelNotes/1.6.0.3.txt +++ b/Documentation/RelNotes/1.6.0.3.txt @@ -50,7 +50,7 @@ Fixes since v1.6.0.2 if the working tree is currently dirty. * "git for-each-ref --format=%(subject)" fixed for commits with no - no newline in the message body. + newline in the message body. * "git remote" fixed to protect printf from user input. diff --git a/Documentation/RelNotes/1.6.2.txt b/Documentation/RelNotes/1.6.2.txt index ad060f4f8900dd..166d73c60fb11e 100644 --- a/Documentation/RelNotes/1.6.2.txt +++ b/Documentation/RelNotes/1.6.2.txt @@ -10,8 +10,8 @@ To ease the transition plan, the receiving repository of such a push running this release will issue a big warning when the configuration variable is missing. Please refer to: - http://git.or.cz/gitwiki/GitFaq#non-bare - http://thread.gmane.org/gmane.comp.version-control.git/107758/focus=108007 + https://archive.kernel.org/oldwiki/git.wiki.kernel.org/index.php/GitFaq.html#non-bare + https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/ for more details on the reason why this change is needed and the transition plan. diff --git a/Documentation/RelNotes/1.6.3.txt b/Documentation/RelNotes/1.6.3.txt index 418c685cf8328a..bbf177fc3c5ba4 100644 --- a/Documentation/RelNotes/1.6.3.txt +++ b/Documentation/RelNotes/1.6.3.txt @@ -10,8 +10,8 @@ To ease the transition plan, the receiving repository of such a push running this release will issue a big warning when the configuration variable is missing. Please refer to: - http://git.or.cz/gitwiki/GitFaq#non-bare - http://thread.gmane.org/gmane.comp.version-control.git/107758/focus=108007 + https://archive.kernel.org/oldwiki/git.wiki.kernel.org/index.php/GitFaq.html#non-bare + https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/ for more details on the reason why this change is needed and the transition plan. diff --git a/Documentation/RelNotes/1.6.4.txt b/Documentation/RelNotes/1.6.4.txt index 7a904419f78150..0fccfb0bf0bddf 100644 --- a/Documentation/RelNotes/1.6.4.txt +++ b/Documentation/RelNotes/1.6.4.txt @@ -10,8 +10,8 @@ To ease the transition plan, the receiving repository of such a push running this release will issue a big warning when the configuration variable is missing. Please refer to: - http://git.or.cz/gitwiki/GitFaq#non-bare - http://thread.gmane.org/gmane.comp.version-control.git/107758/focus=108007 + https://archive.kernel.org/oldwiki/git.wiki.kernel.org/index.php/GitFaq.html#non-bare + https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/ for more details on the reason why this change is needed and the transition plan. diff --git a/Documentation/RelNotes/1.6.5.4.txt b/Documentation/RelNotes/1.6.5.4.txt index d3a2a3e71243dc..344333de66e59b 100644 --- a/Documentation/RelNotes/1.6.5.4.txt +++ b/Documentation/RelNotes/1.6.5.4.txt @@ -10,7 +10,7 @@ Fixes since v1.6.5.3 * "git prune-packed" gave progress output even when its standard error is not connected to a terminal; this caused cron jobs that run it to - produce crufts. + produce cruft. * "git pack-objects --all-progress" is an option to ask progress output from write-object phase _if_ progress output were to be produced, and diff --git a/Documentation/RelNotes/1.6.5.txt b/Documentation/RelNotes/1.6.5.txt index ee141c19add21c..79cb1b2b6df88a 100644 --- a/Documentation/RelNotes/1.6.5.txt +++ b/Documentation/RelNotes/1.6.5.txt @@ -21,8 +21,8 @@ To ease the transition plan, the receiving repository of such a push running this release will issue a big warning when the configuration variable is missing. Please refer to: - http://git.or.cz/gitwiki/GitFaq#non-bare - http://thread.gmane.org/gmane.comp.version-control.git/107758/focus=108007 + https://archive.kernel.org/oldwiki/git.wiki.kernel.org/index.php/GitFaq.html#non-bare + https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/ for more details on the reason why this change is needed and the transition plan. diff --git a/Documentation/RelNotes/1.6.6.txt b/Documentation/RelNotes/1.6.6.txt index c50b59c4957a5d..88b86a827e807e 100644 --- a/Documentation/RelNotes/1.6.6.txt +++ b/Documentation/RelNotes/1.6.6.txt @@ -63,8 +63,8 @@ users will fare this time. Please refer to: - http://git.or.cz/gitwiki/GitFaq#non-bare - http://thread.gmane.org/gmane.comp.version-control.git/107758/focus=108007 + https://archive.kernel.org/oldwiki/git.wiki.kernel.org/index.php/GitFaq.html#non-bare + https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/ for more details on the reason why this change is needed and the transition process that already took place so far. diff --git a/Documentation/RelNotes/1.7.0.2.txt b/Documentation/RelNotes/1.7.0.2.txt index fcb46ca6a4ec32..73ed2b527843e7 100644 --- a/Documentation/RelNotes/1.7.0.2.txt +++ b/Documentation/RelNotes/1.7.0.2.txt @@ -34,7 +34,7 @@ Fixes since v1.7.0.1 * "git status" in 1.7.0 lacked the optimization we used to have in 1.6.X series to speed up scanning of large working tree. - * "gitweb" did not diagnose parsing errors properly while reading tis configuration + * "gitweb" did not diagnose parsing errors properly while reading its configuration file. And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.10.1.txt b/Documentation/RelNotes/1.7.10.1.txt index be68524cff388a..71a86cb7c6d87f 100644 --- a/Documentation/RelNotes/1.7.10.1.txt +++ b/Documentation/RelNotes/1.7.10.1.txt @@ -69,7 +69,7 @@ Fixes since v1.7.10 * The 'push to upstream' implementation was broken in some corner cases. "git push $there" without refspec, when the current branch is set to push to a remote different from $there, used to push to - $there using the upstream information to a remote unreleated to + $there using the upstream information to a remote unrelated to $there. * Giving "--continue" to a conflicted "rebase -i" session skipped a diff --git a/Documentation/RelNotes/1.7.10.4.txt b/Documentation/RelNotes/1.7.10.4.txt index 326670df6e6b87..57597f2bf35d94 100644 --- a/Documentation/RelNotes/1.7.10.4.txt +++ b/Documentation/RelNotes/1.7.10.4.txt @@ -7,7 +7,7 @@ Fixes since v1.7.10.3 * The message file for Swedish translation has been updated a bit. * A name taken from mailmap was copied into an internal buffer - incorrectly and could overun the buffer if it is too long. + incorrectly and could overrun the buffer if it is too long. * A malformed commit object that has a header line chomped in the middle could kill git with a NULL pointer dereference. diff --git a/Documentation/RelNotes/1.7.11.7.txt b/Documentation/RelNotes/1.7.11.7.txt index e7e79d999bd38b..e743a2a8e46ebe 100644 --- a/Documentation/RelNotes/1.7.11.7.txt +++ b/Documentation/RelNotes/1.7.11.7.txt @@ -25,7 +25,7 @@ Fixes since v1.7.11.6 references" nor "Reload" did not update what is shown as the contents of it, when the user overwrote the tag with "git tag -f". - * "git for-each-ref" did not currectly support more than one --sort + * "git for-each-ref" did not correctly support more than one --sort option. * "git log .." errored out saying it is both rev range and a path diff --git a/Documentation/RelNotes/1.7.12.3.txt b/Documentation/RelNotes/1.7.12.3.txt index ecda427a35efb4..4b822976b8adef 100644 --- a/Documentation/RelNotes/1.7.12.3.txt +++ b/Documentation/RelNotes/1.7.12.3.txt @@ -25,7 +25,7 @@ Fixes since v1.7.12.2 its Accept-Encoding header. * "git receive-pack" (the counterpart to "git push") did not give - progress output while processing objects it received to the puser + progress output while processing objects it received to the user when run over the smart-http protocol. * "git status" honored the ignore=dirty settings in .gitmodules but diff --git a/Documentation/RelNotes/1.7.5.3.txt b/Documentation/RelNotes/1.7.5.3.txt index 9c03353af2e940..1d24edcf2fa6bb 100644 --- a/Documentation/RelNotes/1.7.5.3.txt +++ b/Documentation/RelNotes/1.7.5.3.txt @@ -22,7 +22,7 @@ Fixes since v1.7.5.2 * "git log --stdin path" with an input that has additional pathspec used to corrupt memory. - * "git send-pack" (hence "git push") over smalt-HTTP protocol could + * "git send-pack" (hence "git push") over smart-HTTP protocol could deadlock when the client side pack-object died early. * Compressed tarball gitweb generates used to be made with the timestamp diff --git a/Documentation/RelNotes/1.7.7.txt b/Documentation/RelNotes/1.7.7.txt index 7655cccfaa1585..6eff128c80b706 100644 --- a/Documentation/RelNotes/1.7.7.txt +++ b/Documentation/RelNotes/1.7.7.txt @@ -84,7 +84,7 @@ Updates since v1.7.6 logic used by "git diff" to determine the hunk header. * Invoking the low-level "git http-fetch" without "-a" option (which - git itself never did---normal users should not have to worry about + git itself never did--normal users should not have to worry about this) is now deprecated. * The "--decorate" option to "git log" and its family learned to diff --git a/Documentation/RelNotes/1.8.0.txt b/Documentation/RelNotes/1.8.0.txt index 43883c14f08ac0..63d6e4afa4df81 100644 --- a/Documentation/RelNotes/1.8.0.txt +++ b/Documentation/RelNotes/1.8.0.txt @@ -233,7 +233,7 @@ to them for details). together, misdetected branches. * "git receive-pack" (the counterpart to "git push") did not give - progress output while processing objects it received to the puser + progress output while processing objects it received to the user when run over the smart-http protocol. * When you misspell the command name you give to the "exec" action in diff --git a/Documentation/RelNotes/1.8.3.1.txt b/Documentation/RelNotes/1.8.3.1.txt index fc3ea185a5e6f3..986637b7551f14 100644 --- a/Documentation/RelNotes/1.8.3.1.txt +++ b/Documentation/RelNotes/1.8.3.1.txt @@ -1,5 +1,5 @@ Git v1.8.3.1 Release Notes -======================== +========================== Fixes since v1.8.3 ------------------ diff --git a/Documentation/RelNotes/1.8.4.1.txt b/Documentation/RelNotes/1.8.4.1.txt index 3aa25a274379dc..c257beb114c9fc 100644 --- a/Documentation/RelNotes/1.8.4.1.txt +++ b/Documentation/RelNotes/1.8.4.1.txt @@ -1,5 +1,5 @@ Git v1.8.4.1 Release Notes -======================== +========================== Fixes since v1.8.4 ------------------ @@ -15,7 +15,7 @@ Fixes since v1.8.4 in 1.8.4-rc1). * "git rebase -i" and other scripted commands were feeding a - random, data dependant error message to 'echo' and expecting it + random, data dependent error message to 'echo' and expecting it to come out literally. * Setting the "submodule..path" variable to the empty diff --git a/Documentation/RelNotes/1.8.4.2.txt b/Documentation/RelNotes/1.8.4.2.txt index 9adccb1efb8d3f..bf6fb1a0236984 100644 --- a/Documentation/RelNotes/1.8.4.2.txt +++ b/Documentation/RelNotes/1.8.4.2.txt @@ -1,5 +1,5 @@ Git v1.8.4.2 Release Notes -======================== +========================== Fixes since v1.8.4.1 -------------------- diff --git a/Documentation/RelNotes/1.8.4.3.txt b/Documentation/RelNotes/1.8.4.3.txt index 03f3d177518c70..267a1b34b4d899 100644 --- a/Documentation/RelNotes/1.8.4.3.txt +++ b/Documentation/RelNotes/1.8.4.3.txt @@ -1,5 +1,5 @@ Git v1.8.4.3 Release Notes -======================== +========================== Fixes since v1.8.4.2 -------------------- diff --git a/Documentation/RelNotes/1.8.4.4.txt b/Documentation/RelNotes/1.8.4.4.txt index 7bc4c5dcc01b14..a7c1ce15c06172 100644 --- a/Documentation/RelNotes/1.8.4.4.txt +++ b/Documentation/RelNotes/1.8.4.4.txt @@ -1,5 +1,5 @@ Git v1.8.4.4 Release Notes -======================== +========================== Fixes since v1.8.4.3 -------------------- diff --git a/Documentation/RelNotes/1.8.4.txt b/Documentation/RelNotes/1.8.4.txt index 02f681b71051a9..2e7529928b6d6c 100644 --- a/Documentation/RelNotes/1.8.4.txt +++ b/Documentation/RelNotes/1.8.4.txt @@ -58,7 +58,7 @@ Foreign interfaces, subsystems and ports. credential helper interface from Git.pm. * Update build for Cygwin 1.[57]. Torsten Bögershausen reports that - this is fine with Cygwin 1.7 ($gmane/225824) so let's try moving it + this is fine with Cygwin 1.7 (cf. <51A606A0.5060101@web.de>) so let's try moving it ahead. * The credential helper to talk to keychain on OS X (in contrib/) has @@ -365,7 +365,7 @@ details). (merge 2fbd4f9 mh/maint-lockfile-overflow later to maint). * Invocations of "git checkout" used internally by "git rebase" were - counted as "checkout", and affected later "git checkout -" to the + counted as "checkout", and affected later "git checkout -", which took the user to an unexpected place. (merge 3bed291 rr/rebase-checkout-reflog later to maint). diff --git a/Documentation/RelNotes/1.8.5.6.txt b/Documentation/RelNotes/1.8.5.6.txt new file mode 100644 index 00000000000000..92ff92b1e6e2c1 --- /dev/null +++ b/Documentation/RelNotes/1.8.5.6.txt @@ -0,0 +1,34 @@ +Git v1.8.5.6 Release Notes +========================== + +Fixes since v1.8.5.5 +-------------------- + + * We used to allow committing a path ".Git/config" with Git that is + running on a case sensitive filesystem, but an attempt to check out + such a path with Git that runs on a case insensitive filesystem + would have clobbered ".git/config", which is definitely not what + the user would have expected. Git now prevents you from tracking + a path with ".Git" (in any case combination) as a path component. + + * On Windows, certain path components that are different from ".git" + are mapped to ".git", e.g. "git~1/config" is treated as if it were + ".git/config". HFS+ has a similar issue, where certain unicode + codepoints are ignored, e.g. ".g\u200cit/config" is treated as if + it were ".git/config". Pathnames with these potential issues are + rejected on the affected systems. Git on systems that are not + affected by this issue (e.g. Linux) can also be configured to + reject them to ensure cross platform interoperability of the hosted + projects. + + * "git fsck" notices a tree object that records such a path that can + be confused with ".git", and with receive.fsckObjects configuration + set to true, an attempt to "git push" such a tree object will be + rejected. Such a path may not be a problem on a well behaving + filesystem but in order to protect those on HFS+ and on case + insensitive filesystems, this check is enabled on all platforms. + +A big "thanks!" for bringing this issue to us goes to our friends in +the Mercurial land, namely, Matt Mackall and Augie Fackler. + +Also contains typofixes, documentation updates and trivial code clean-ups. diff --git a/Documentation/RelNotes/1.9.0.txt b/Documentation/RelNotes/1.9.0.txt index 752d79127a3d7a..4e4b88aa5c8944 100644 --- a/Documentation/RelNotes/1.9.0.txt +++ b/Documentation/RelNotes/1.9.0.txt @@ -177,7 +177,7 @@ Performance, Internal Implementation, etc. * The naming convention of the packfiles has been updated; it used to be based on the enumeration of names of the objects that are contained in the pack, but now it also depends on how the packed - result is represented---packing the same set of objects using + result is represented--packing the same set of objects using different settings (or delta order) would produce a pack with different name. diff --git a/Documentation/RelNotes/1.9.5.txt b/Documentation/RelNotes/1.9.5.txt new file mode 100644 index 00000000000000..8d6ac0cf53570b --- /dev/null +++ b/Documentation/RelNotes/1.9.5.txt @@ -0,0 +1,34 @@ +Git v1.9.5 Release Notes +======================== + +Fixes since v1.9.4 +------------------ + + * We used to allow committing a path ".Git/config" with Git that is + running on a case sensitive filesystem, but an attempt to check out + such a path with Git that runs on a case insensitive filesystem + would have clobbered ".git/config", which is definitely not what + the user would have expected. Git now prevents you from tracking + a path with ".Git" (in any case combination) as a path component. + + * On Windows, certain path components that are different from ".git" + are mapped to ".git", e.g. "git~1/config" is treated as if it were + ".git/config". HFS+ has a similar issue, where certain unicode + codepoints are ignored, e.g. ".g\u200cit/config" is treated as if + it were ".git/config". Pathnames with these potential issues are + rejected on the affected systems. Git on systems that are not + affected by this issue (e.g. Linux) can also be configured to + reject them to ensure cross platform interoperability of the hosted + projects. + + * "git fsck" notices a tree object that records such a path that can + be confused with ".git", and with receive.fsckObjects configuration + set to true, an attempt to "git push" such a tree object will be + rejected. Such a path may not be a problem on a well behaving + filesystem but in order to protect those on HFS+ and on case + insensitive filesystems, this check is enabled on all platforms. + +A big "thanks!" for bringing this issue to us goes to our friends in +the Mercurial land, namely, Matt Mackall and Augie Fackler. + +Also contains typofixes, documentation updates and trivial code clean-ups. diff --git a/Documentation/RelNotes/2.0.5.txt b/Documentation/RelNotes/2.0.5.txt new file mode 100644 index 00000000000000..3a16f697e818f3 --- /dev/null +++ b/Documentation/RelNotes/2.0.5.txt @@ -0,0 +1,34 @@ +Git v2.0.5 Release Notes +======================== + +Fixes since v2.0.4 +------------------ + + * We used to allow committing a path ".Git/config" with Git that is + running on a case sensitive filesystem, but an attempt to check out + such a path with Git that runs on a case insensitive filesystem + would have clobbered ".git/config", which is definitely not what + the user would have expected. Git now prevents you from tracking + a path with ".Git" (in any case combination) as a path component. + + * On Windows, certain path components that are different from ".git" + are mapped to ".git", e.g. "git~1/config" is treated as if it were + ".git/config". HFS+ has a similar issue, where certain unicode + codepoints are ignored, e.g. ".g\u200cit/config" is treated as if + it were ".git/config". Pathnames with these potential issues are + rejected on the affected systems. Git on systems that are not + affected by this issue (e.g. Linux) can also be configured to + reject them to ensure cross platform interoperability of the hosted + projects. + + * "git fsck" notices a tree object that records such a path that can + be confused with ".git", and with receive.fsckObjects configuration + set to true, an attempt to "git push" such a tree object will be + rejected. Such a path may not be a problem on a well behaving + filesystem but in order to protect those on HFS+ and on case + insensitive filesystems, this check is enabled on all platforms. + +A big "thanks!" for bringing this issue to us goes to our friends in +the Mercurial land, namely, Matt Mackall and Augie Fackler. + +Also contains typofixes, documentation updates and trivial code clean-ups. diff --git a/Documentation/RelNotes/2.1.1.txt b/Documentation/RelNotes/2.1.1.txt new file mode 100644 index 00000000000000..830fc3cc6dd7e4 --- /dev/null +++ b/Documentation/RelNotes/2.1.1.txt @@ -0,0 +1,44 @@ +Git v2.1.1 Release Notes +======================== + + * Git 2.0 had a regression where "git fetch" into a shallowly + cloned repository from a repository with bitmap object index + enabled did not work correctly. This has been corrected. + + * Git 2.0 had a regression which broke (rarely used) "git diff-tree + -t". This has been corrected. + + * "git log --pretty/format=" with an empty format string did not + mean the more obvious "No output whatsoever" but "Use default + format", which was counterintuitive. Now it means "nothing shown + for the log message part". + + * "git -c section.var command" and "git -c section.var= command" + should pass the configuration differently (the former should be a + boolean true, the latter should be an empty string), but they + didn't work that way. Now it does. + + * Applying a patch not generated by Git in a subdirectory used to + check the whitespace breakage using the attributes for incorrect + paths. Also whitespace checks were performed even for paths + excluded via "git apply --exclude=" mechanism. + + * "git bundle create" with date-range specification were meant to + exclude tags outside the range, but it did not work correctly. + + * "git add x" where x that used to be a directory has become a + symbolic link to a directory misbehaved. + + * The prompt script checked $GIT_DIR/ref/stash file to see if there + is a stash, which was a no-no. + + * "git checkout -m" did not switch to another branch while carrying + the local changes forward when a path was deleted from the index. + + * With sufficiently long refnames, fast-import could have overflown + an on-stack buffer. + + * After "pack-refs --prune" packed refs at the top-level, it failed + to prune them. + + * "git gc --auto" triggered from "git fetch --quiet" was not quiet. diff --git a/Documentation/RelNotes/2.1.2.txt b/Documentation/RelNotes/2.1.2.txt new file mode 100644 index 00000000000000..abc3b8928a0045 --- /dev/null +++ b/Documentation/RelNotes/2.1.2.txt @@ -0,0 +1,20 @@ +Git v2.1.2 Release Notes +======================== + + * "git push" over HTTP transport had an artificial limit on number of + refs that can be pushed imposed by the command line length. + + * When receiving an invalid pack stream that records the same object + twice, multiple threads got confused due to a race. + + * An attempt to remove the entire tree in the "git fast-import" input + stream caused it to misbehave. + + * Reachability check (used in "git prune" and friends) did not add a + detached HEAD as a starting point to traverse objects still in use. + + * "git config --add section.var val" used to lose existing + section.var whose value was an empty string. + + * "git fsck" failed to report that it found corrupt objects via its + exit status in some cases. diff --git a/Documentation/RelNotes/2.1.3.txt b/Documentation/RelNotes/2.1.3.txt new file mode 100644 index 00000000000000..0dfb17c4fc6fca --- /dev/null +++ b/Documentation/RelNotes/2.1.3.txt @@ -0,0 +1,26 @@ +Git v2.1.3 Release Notes +======================== + + * Some MUAs mangled a line in a message that begins with "From " to + ">From " when writing to a mailbox file and feeding such an input to + "git am" used to lose such a line. + + * "git daemon" (with NO_IPV6 build configuration) used to incorrectly + use the hostname even when gethostbyname() reported that the given + hostname is not found. + + * Newer versions of 'meld' breaks the auto-detection we use to see if + they are new enough to support the `--output` option. + + * "git pack-objects" forgot to disable the codepath to generate + object reachability bitmap when it needs to split the resulting + pack. + + * "gitweb" used deprecated CGI::startfrom, which was removed from + CGI.pm as of 4.04; use CGI::start_from instead. + + * "git log" documentation had an example section marked up not + quite correctly, which passed AsciiDoc but failed with + AsciiDoctor. + +Also contains some documentation updates. diff --git a/Documentation/RelNotes/2.1.4.txt b/Documentation/RelNotes/2.1.4.txt new file mode 100644 index 00000000000000..d16e5f041f5d3a --- /dev/null +++ b/Documentation/RelNotes/2.1.4.txt @@ -0,0 +1,34 @@ +Git v2.1.4 Release Notes +======================== + +Fixes since v2.1.3 +------------------ + + * We used to allow committing a path ".Git/config" with Git that is + running on a case sensitive filesystem, but an attempt to check out + such a path with Git that runs on a case insensitive filesystem + would have clobbered ".git/config", which is definitely not what + the user would have expected. Git now prevents you from tracking + a path with ".Git" (in any case combination) as a path component. + + * On Windows, certain path components that are different from ".git" + are mapped to ".git", e.g. "git~1/config" is treated as if it were + ".git/config". HFS+ has a similar issue, where certain unicode + codepoints are ignored, e.g. ".g\u200cit/config" is treated as if + it were ".git/config". Pathnames with these potential issues are + rejected on the affected systems. Git on systems that are not + affected by this issue (e.g. Linux) can also be configured to + reject them to ensure cross platform interoperability of the hosted + projects. + + * "git fsck" notices a tree object that records such a path that can + be confused with ".git", and with receive.fsckObjects configuration + set to true, an attempt to "git push" such a tree object will be + rejected. Such a path may not be a problem on a well behaving + filesystem but in order to protect those on HFS+ and on case + insensitive filesystems, this check is enabled on all platforms. + +A big "thanks!" for bringing this issue to us goes to our friends in +the Mercurial land, namely, Matt Mackall and Augie Fackler. + +Also contains typofixes, documentation updates and trivial code clean-ups. diff --git a/Documentation/RelNotes/2.10.0.txt b/Documentation/RelNotes/2.10.0.txt new file mode 100644 index 00000000000000..3792b7d03d5f79 --- /dev/null +++ b/Documentation/RelNotes/2.10.0.txt @@ -0,0 +1,675 @@ +Git 2.10 Release Notes +====================== + +Backward compatibility notes +---------------------------- + +Updates since v2.9 +------------------ + +UI, Workflows & Features + + * "git pull --rebase --verify-signature" learned to warn the user + that "--verify-signature" is a no-op when rebasing. + + * An upstream project can make a recommendation to shallowly clone + some submodules in the .gitmodules file it ships. + + * "git worktree add" learned that '-' can be used as a short-hand for + "@{-1}", the previous branch. + + * Update the funcname definition to support css files. + + * The completion script (in contrib/) learned to complete "git + status" options. + + * Messages that are generated by auto gc during "git push" on the + receiving end are now passed back to the sending end in such a way + that they are shown with "remote: " prefix to avoid confusing the + users. + + * "git add -i/-p" learned to honor diff.compactionHeuristic + experimental knob, so that the user can work on the same hunk split + as "git diff" output. + + * "upload-pack" allows a custom "git pack-objects" replacement when + responding to "fetch/clone" via the uploadpack.packObjectsHook. + (merge b738396 jk/upload-pack-hook later to maint). + + * Teach format-patch and mailsplit (hence "am") how a line that + happens to begin with "From " in the e-mail message is quoted with + ">", so that these lines can be restored to their original shape. + (merge d9925d1 ew/mboxrd-format-am later to maint). + + * "git repack" learned the "--keep-unreachable" option, which sends + loose unreachable objects to a pack instead of leaving them loose. + This helps heuristics based on the number of loose objects + (e.g. "gc --auto"). + (merge e26a8c4 jk/repack-keep-unreachable later to maint). + + * "log --graph --format=" learned that "%>|(N)" specifies the width + relative to the terminal's left edge, not relative to the area to + draw text that is to the right of the ancestry-graph section. It + also now accepts negative N that means the column limit is relative + to the right border. + + * A careless invocation of "git send-email directory/" after editing + 0001-change.patch with an editor often ends up sending both + 0001-change.patch and its backup file, 0001-change.patch~, causing + embarrassment and a minor confusion. Detect such an input and + offer to skip the backup files when sending the patches out. + (merge 531220b jc/send-email-skip-backup later to maint). + + * "git submodule update" that drives many "git clone" could + eventually hit flaky servers/network conditions on one of the + submodules; the command learned to retry the attempt. + + * The output coloring scheme learned two new attributes, italic and + strike, in addition to existing bold, reverse, etc. + + * "git log" learns log.showSignature configuration variable, and a + command line option "--no-show-signature" to countermand it. + (merge fce04c3 mj/log-show-signature-conf later to maint). + + * More markings of messages for i18n, with updates to various tests + to pass GETTEXT_POISON tests. + + * "git archive" learned to handle files that are larger than 8GB and + commits far in the future than expressible by the traditional US-TAR + format. + (merge 560b0e8 jk/big-and-future-archive-tar later to maint). + + + * A new configuration variable core.sshCommand has been added to + specify what value for GIT_SSH_COMMAND to use per repository. + + * "git worktree prune" protected worktrees that are marked as + "locked" by creating a file in a known location. "git worktree" + command learned a dedicated command pair to create and remove such + a file, so that the users do not have to do this with editor. + + * A handful of "git svn" updates. + + * "git push" learned to accept and pass extra options to the + receiving end so that hooks can read and react to them. + + * "git status" learned to suggest "merge --abort" during a conflicted + merge, just like it already suggests "rebase --abort" during a + conflicted rebase. + + * "git jump" script (in contrib/) has been updated a bit. + (merge a91e692 jk/git-jump later to maint). + + * "git push" and "git clone" learned to give better progress meters + to the end user who is waiting on the terminal. + + * An entry "git log --decorate" for the tip of the current branch is + shown as "HEAD -> name" (where "name" is the name of the branch); + the arrow is now painted in the same color as "HEAD", not in the + color for commits. + + * "git format-patch" learned format.from configuration variable to + specify the default settings for its "--from" option. + + * "git am -3" calls "git merge-recursive" when it needs to fall back + to a three-way merge; this call has been turned into an internal + subroutine call instead of spawning a separate subprocess. + + * The command line completion scripts (in contrib/) now knows about + "git branch --delete/--move [--remote]". + (merge 2703c22 vs/completion-branch-fully-spelled-d-m-r later to maint). + + * "git rev-parse --git-path hooks/" learned to take + core.hooksPath configuration variable (introduced during 2.9 cycle) + into account. + (merge 9445b49 ab/hooks later to maint). + + * "git log --show-signature" and other commands that display the + verification status of PGP signature now shows the longer key-id, + as 32-bit key-id is so last century. + + +Performance, Internal Implementation, Development Support etc. + + * "git fast-import" learned the same performance trick to avoid + creating too small a packfile as "git fetch" and "git push" have, + using *.unpackLimit configuration. + + * When "git daemon" is run without --[init-]timeout specified, a + connection from a client that silently goes offline can hang around + for a long time, wasting resources. The socket-level KEEPALIVE has + been enabled to allow the OS to notice such failed connections. + + * "git upload-pack" command has been updated to use the parse-options + API. + + * The "git apply" standalone program is being libified; the first + step to move many state variables into a structure that can be + explicitly (re)initialized to make the machinery callable more + than once has been merged. + + * HTTP transport gained an option to produce more detailed debugging + trace. + (merge 73e57aa ep/http-curl-trace later to maint). + + * Instead of taking advantage of the fact that a struct string_list + that is allocated with all NULs happens to be the INIT_NODUP kind, + the users of string_list structures are taught to initialize them + explicitly as such, to document their behaviour better. + (merge 2721ce2 jk/string-list-static-init later to maint). + + * HTTPd tests learned to show the server error log to help diagnosing + a failing tests. + (merge 44f243d nd/test-lib-httpd-show-error-log-in-verbose later to maint). + + * The ownership rule for the piece of memory that hold references to + be fetched in "git fetch" was screwy, which has been cleaned up. + + * "git bisect" makes an internal call to "git diff-tree" when + bisection finds the culprit, but this call did not initialize the + data structure to pass to the diff-tree API correctly. + + * Further preparatory clean-up for "worktree" feature continues. + (merge 0409e0b nd/worktree-cleanup-post-head-protection later to maint). + + * Formats of the various data (and how to validate them) where we use + GPG signature have been documented. + + * A new run-command API function pipe_command() is introduced to + sanely feed data to the standard input while capturing data from + the standard output and the standard error of an external process, + which is cumbersome to hand-roll correctly without deadlocking. + + * The codepath to sign data in a prepared buffer with GPG has been + updated to use this API to read from the status-fd to check for + errors (instead of relying on GPG's exit status). + (merge efee955 jk/gpg-interface-cleanup later to maint). + + * Allow t/perf framework to use the features from the most recent + version of Git even when testing an older installed version. + + * The commands in the "log/diff" family have had an FILE* pointer in the + data structure they pass around for a long time, but some codepaths + used to always write to the standard output. As a preparatory step + to make "git format-patch" available to the internal callers, these + codepaths have been updated to consistently write into that FILE* + instead. + + * Conversion from unsigned char sha1[20] to struct object_id + continues. + + * Improve the look of the way "git fetch" reports what happened to + each ref that was fetched. + + * The .c/.h sources are marked as such in our .gitattributes file so + that "git diff -W" and friends would work better. + + * Code clean-up to avoid using a variable string that compilers may + feel untrustable as printf-style format given to write_file() + helper function. + + * "git p4" used a location outside $GIT_DIR/refs/ to place its + temporary branches, which has been moved to refs/git-p4-tmp/. + + * Existing autoconf generated test for the need to link with pthread + library did not check all the functions from pthread libraries; + recent FreeBSD has some functions in libc but not others, and we + mistakenly thought linking with libc is enough when it is not. + + * When "git fsck" reports a broken link (e.g. a tree object contains + a blob that does not exist), both containing object and the object + that is referred to were reported with their 40-hex object names. + The command learned the "--name-objects" option to show the path to + the containing object from existing refs (e.g. "HEAD~24^2:file.txt"). + + * Allow http daemon tests in Travis CI tests. + + * Makefile assumed that -lrt is always available on platforms that + want to use clock_gettime() and CLOCK_MONOTONIC, which is not a + case for recent Mac OS X. The necessary symbols are often found in + libc on many modern systems and having -lrt on the command line, as + long as the library exists, had no effect, but when the platform + removes librt.a that is a different matter--having -lrt will break + the linkage. + + This change could be seen as a regression for those who do need to + specify -lrt, as they now specifically ask for NEEDS_LIBRT when + building. Hopefully they are in the minority these days. + + * Further preparatory work on the refs API before the pluggable + backend series can land. + + * Error handling in the codepaths that updates refs has been + improved. + + * The API to iterate over all the refs (i.e. for_each_ref(), etc.) + has been revamped. + + * The handling of the "text=auto" attribute has been corrected. + $ echo "* text=auto eol=crlf" >.gitattributes + used to have the same effect as + $ echo "* text eol=crlf" >.gitattributes + i.e. declaring all files are text (ignoring "auto"). The + combination has been fixed to be equivalent to doing + $ git config core.autocrlf true + + * Documentation has been updated to show better example usage + of the updated "text=auto" attribute. + + * A few tests that specifically target "git rebase -i" have been + added. + + * Dumb http transport on the client side has been optimized. + (merge ecba195 ew/http-walker later to maint). + + * Users of the parse_options_concat() API function need to allocate + extra slots in advance and fill them with OPT_END() when they want + to decide the set of supported options dynamically, which makes the + code error-prone and hard to read. This has been corrected by tweaking + the API to allocate and return a new copy of "struct option" array. + + * "git fetch" exchanges batched have/ack messages between the sender + and the receiver, initially doubling every time and then falling + back to enlarge the window size linearly. The "smart http" + transport, being an half-duplex protocol, outgrows the preset limit + too quickly and becomes inefficient when interacting with a large + repository. The internal mechanism learned to grow the window size + more aggressively when working with the "smart http" transport. + + * Tests for "git svn" have been taught to reuse the lib-httpd test + infrastructure when testing the subversion integration that + interacts with subversion repositories served over the http:// + protocol. + (merge a8a5d25 ew/git-svn-http-tests later to maint). + + * "git pack-objects" has a few options that tell it not to pack + objects found in certain packfiles, which require it to scan .idx + files of all available packs. The codepaths involved in these + operations have been optimized for a common case of not having any + non-local pack and/or any .kept pack. + + * The t3700 test about "add --chmod=-x" have been made a bit more + robust and generally cleaned up. + (merge 766cdc4 ib/t3700-add-chmod-x-updates later to maint). + + * The build procedure learned PAGER_ENV knob that lists what default + environment variable settings to export for popular pagers. This + mechanism is used to tweak the default settings to MORE on FreeBSD. + (merge 995bc22 ew/build-time-pager-tweaks later to maint). + + * The http-backend (the server-side component of smart-http + transport) used to trickle the HTTP header one at a time. Now + these write(2)s are batched. + (merge b36045c ew/http-backend-batch-headers later to maint). + + * When "git rebase" tries to compare set of changes on the updated + upstream and our own branch, it computes patch-id for all of these + changes and attempts to find matches. This has been optimized by + lazily computing the full patch-id (which is expensive) to be + compared only for changes that touch the same set of paths. + (merge ba67504 kw/patch-ids-optim later to maint). + + * A handful of tests that were broken under gettext-poison build have + been fixed. + + * The recent i18n patch we added during this cycle did a bit too much + refactoring of the messages to avoid word-legos; the repetition has + been reduced to help translators. + + +Also contains various documentation updates and code clean-ups. + + +Fixes since v2.9 +---------------- + +Unless otherwise noted, all the fixes since v2.8 in the maintenance +track are contained in this release (see the maintenance releases' +notes for details). + + * The commands in `git log` family take %C(auto) in a custom format + string. This unconditionally turned the color on, ignoring + --no-color or with --color=auto when the output is not connected to + a tty; this was corrected to make the format truly behave as + "auto". + + * "git rev-list --count" whose walk-length is limited with "-n" + option did not work well with the counting optimized to look at the + bitmap index. + + * "git show -W" (extend hunks to cover the entire function, delimited + by lines that match the "funcname" pattern) used to show the entire + file when a change added an entire function at the end of the file, + which has been fixed. + + * The documentation set has been updated so that literal commands, + configuration variables and environment variables are consistently + typeset in fixed-width font and bold in manpages. + + * "git svn propset" subcommand that was added in 2.3 days is + documented now. + + * The documentation tries to consistently spell "GPG"; when + referring to the specific program name, "gpg" is used. + + * "git reflog" stopped upon seeing an entry that denotes a branch + creation event (aka "unborn"), which made it appear as if the + reflog was truncated. + + * The git-prompt scriptlet (in contrib/) was not friendly with those + who uses "set -u", which has been fixed. + + * compat/regex code did not cleanly compile. + + * A codepath that used alloca(3) to place an unbounded amount of data + on the stack has been updated to avoid doing so. + + * "git update-index --add --chmod=+x file" may be usable as an escape + hatch, but not a friendly thing to force for people who do need to + use it regularly. "git add --chmod=+x file" can be used instead. + + * Build improvements for gnome-keyring (in contrib/) + + * "git status" used to say "working directory" when it meant "working + tree". + + * Comments about misbehaving FreeBSD shells have been clarified with + the version number (9.x and before are broken, newer ones are OK). + + * "git cherry-pick A" worked on an unborn branch, but "git + cherry-pick A..B" didn't. + + * Fix an unintended regression in v2.9 that breaks "clone --depth" + that recurses down to submodules by forcing the submodules to also + be cloned shallowly, which many server instances that host upstream + of the submodules are not prepared for. + + * Fix unnecessarily waste in the idiomatic use of ': ${VAR=default}' + to set the default value, without enclosing it in double quotes. + + * Some platform-specific code had non-ANSI strict declarations of C + functions that do not take any parameters, which has been + corrected. + + * The internal code used to show local timezone offset is not + prepared to handle timestamps beyond year 2100, and gave a + bogus offset value to the caller. Use a more benign looking + +0000 instead and let "git log" going in such a case, instead + of aborting. + + * One among four invocations of readlink(1) in our test suite has + been rewritten so that the test can run on systems without the + command (others are in valgrind test framework and t9802). + + * t/perf needs /usr/bin/time with GNU extension; the invocation of it + is updated to "gtime" on Darwin. + + * A bug, which caused "git p4" while running under verbose mode to + report paths that are omitted due to branch prefix incorrectly, has + been fixed; the command said "Ignoring file outside of prefix" for + paths that are _inside_. + + * The top level documentation "git help git" still pointed at the + documentation set hosted at now-defunct google-code repository. + Update it to point to https://git.github.io/htmldocs/git.html + instead. + + * A helper function that takes the contents of a commit object and + finds its subject line did not ignore leading blank lines, as is + commonly done by other codepaths. Make it ignore leading blank + lines to match. + + * For a long time, we carried an in-code comment that said our + colored output would work only when we use fprintf/fputs on + Windows, which no longer is the case for the past few years. + + * "gc.autoPackLimit" when set to 1 should not trigger a repacking + when there is only one pack, but the code counted poorly and did + so. + + * Add a test to specify the desired behaviour that currently is not + available in "git rebase -Xsubtree=...". + + * More mark-up updates to typeset strings that are expected to + literally typed by the end user in fixed-width font. + + * "git commit --amend --allow-empty-message -S" for a commit without + any message body could have misidentified where the header of the + commit object ends. + + * "git rebase -i --autostash" did not restore the auto-stashed change + when the operation was aborted. + + * Git does not know what the contents in the index should be for a + path added with "git add -N" yet, so "git grep --cached" should not + show hits (or show lack of hits, with -L) in such a path, but that + logic does not apply to "git grep", i.e. searching in the working + tree files. But we did so by mistake, which has been corrected. + + * "git blame -M" missed a single line that was moved within the file. + + * Fix recently introduced codepaths that are involved in parallel + submodule operations, which gave up on reading too early, and + could have wasted CPU while attempting to write under a corner + case condition. + + * "git grep -i" has been taught to fold case in non-ascii locales + correctly. + + * A test that unconditionally used "mktemp" learned that the command + is not necessarily available everywhere. + + * There are certain house-keeping tasks that need to be performed at + the very beginning of any Git program, and programs that are not + built-in commands had to do them exactly the same way as "git" + potty does. It was easy to make mistakes in one-off standalone + programs (like test helpers). A common "main()" function that + calls cmd_main() of individual program has been introduced to + make it harder to make mistakes. + (merge de61ceb jk/common-main later to maint). + + * The test framework learned a new helper test_match_signal to + check an exit code from getting killed by an expected signal. + + * General code clean-up around a helper function to write a + single-liner to a file. + (merge 7eb6e10 jk/write-file later to maint). + + * One part of "git am" had an oddball helper function that called + stuff from outside "his" as opposed to calling what we have "ours", + which was not gender-neutral and also inconsistent with the rest of + the system where outside stuff is usually called "theirs" in + contrast to "ours". + + * "git blame file" allowed the lineage of lines in the uncommitted, + unadded contents of "file" to be inspected, but it refused when + "file" did not appear in the current commit. When "file" was + created by renaming an existing file (but the change has not been + committed), this restriction was unnecessarily tight. + + * "git add -N dir/file && git write-tree" produced an incorrect tree + when there are other paths in the same directory that sorts after + "file". + + * "git fetch http://user:pass@host/repo..." scrubbed the userinfo + part, but "git push" didn't. + + * "git merge" with renormalization did not work well with + merge-recursive, due to "safer crlf" conversion kicking in when it + shouldn't. + (merge 1335d76 jc/renormalize-merge-kill-safer-crlf later to maint). + + * The use of strbuf in "git rm" to build filename to remove was a bit + suboptimal, which has been fixed. + + * An age old bug that caused "git diff --ignore-space-at-eol" + misbehave has been fixed. + + * "git notes merge" had a code to see if a path exists (and fails if + it does) and then open the path for writing (when it doesn't). + Replace it with open with O_EXCL. + + * "git pack-objects" and "git index-pack" mostly operate with off_t + when talking about the offset of objects in a packfile, but there + were a handful of places that used "unsigned long" to hold that + value, leading to an unintended truncation. + + * Recent update to "git daemon" tries to enable the socket-level + KEEPALIVE, but when it is spawned via inetd, the standard input + file descriptor may not necessarily be connected to a socket. + Suppress an ENOTSOCK error from setsockopt(). + + * Recent FreeBSD stopped making perl available at /usr/bin/perl; + switch the default the built-in path to /usr/local/bin/perl on not + too ancient FreeBSD releases. + + * "git commit --help" said "--no-verify" is only about skipping the + pre-commit hook, and failed to say that it also skipped the + commit-msg hook. + + * "git merge" in Git v2.9 was taught to forbid merging an unrelated + lines of history by default, but that is exactly the kind of thing + the "--rejoin" mode of "git subtree" (in contrib/) wants to do. + "git subtree" has been taught to use the "--allow-unrelated-histories" + option to override the default. + + * The build procedure for "git persistent-https" helper (in contrib/) + has been updated so that it can be built with more recent versions + of Go. + + * There is an optimization used in "git diff $treeA $treeB" to borrow + an already checked-out copy in the working tree when it is known to + be the same as the blob being compared, expecting that open/mmap of + such a file is faster than reading it from the object store, which + involves inflating and applying delta. This however kicked in even + when the checked-out copy needs to go through the convert-to-git + conversion (including the clean filter), which defeats the whole + point of the optimization. The optimization has been disabled when + the conversion is necessary. + + * "git -c grep.patternType=extended log --basic-regexp" misbehaved + because the internal API to access the grep machinery was not + designed well. + + * Windows port was failing some tests in t4130, due to the lack of + inum in the returned values by its lstat(2) emulation. + + * The reflog output format is documented better, and a new format + --date=unix to report the seconds-since-epoch (without timezone) + has been added. + (merge 442f6fd jk/reflog-date later to maint). + + * "git difftool ..." started in a subdirectory failed to + interpret the paths relative to that directory, which has been + fixed. + + * The characters in the label shown for tags/refs for commits in + "gitweb" output are now properly escaped for proper HTML output. + + * FreeBSD can lie when asked mtime of a directory, which made the + untracked cache code to fall back to a slow-path, which in turn + caused tests in t7063 to fail because it wanted to verify the + behaviour of the fast-path. + + * Squelch compiler warnings for nedmalloc (in compat/) library. + + * A small memory leak in the command line parsing of "git blame" + has been plugged. + + * The API documentation for hashmap was unclear if hashmap_entry + can be safely discarded without any other consideration. State + that it is safe to do so. + + * Not-so-recent rewrite of "git am" that started making internal + calls into the commit machinery had an unintended regression, in + that no matter how many seconds it took to apply many patches, the + resulting committer timestamp for the resulting commits were all + the same. + + * "git push --force-with-lease" already had enough logic to allow + ensuring that such a push results in creation of a ref (i.e. the + receiving end did not have another push from sideways that would be + discarded by our force-pushing), but didn't expose this possibility + to the users. It does so now. + (merge 9eed4f3 jk/push-force-with-lease-creation later to maint). + + * The mechanism to limit the pack window memory size, when packing is + done using multiple threads (which is the default), is per-thread, + but this was not documented clearly. + (merge 954176c ms/document-pack-window-memory-is-per-thread later to maint). + + * "import-tars" fast-import script (in contrib/) used to ignore a + hardlink target and replaced it with an empty file, which has been + corrected to record the same blob as the other file the hardlink is + shared with. + (merge 04e0869 js/import-tars-hardlinks later to maint). + + * "git mv dir non-existing-dir/" did not work in some environments + the same way as existing mainstream platforms. The code now moves + "dir" to "non-existing-dir", without relying on rename("A", "B/") + that strips the trailing slash of '/'. + (merge 189d035 js/mv-dir-to-new-directory later to maint). + + * The "t/" hierarchy is prone to get an unusual pathname; "make test" + has been taught to make sure they do not contain paths that cannot + be checked out on Windows (and the mechanism can be reusable to + catch pathnames that are not portable to other platforms as need + arises). + (merge c2cafd3 js/test-lint-pathname later to maint). + + * When "git merge-recursive" works on history with many criss-cross + merges in "verbose" mode, the names the command assigns to the + virtual merge bases could have overwritten each other by unintended + reuse of the same piece of memory. + (merge 5447a76 rs/pull-signed-tag later to maint). + + * "git checkout --detach " used to give the same advice + message as that is issued when "git checkout " (or anything + that is not a branch name) is given, but asking with "--detach" is + an explicit enough sign that the user knows what is going on. The + advice message has been squelched in this case. + (merge 779b88a sb/checkout-explit-detach-no-advice later to maint). + + * "git difftool" by default ignores the error exit from the backend + commands it spawns, because often they signal that they found + differences by exiting with a non-zero status code just like "diff" + does; the exit status codes 126 and above however are special in + that they are used to signal that the command is not executable, + does not exist, or killed by a signal. "git difftool" has been + taught to notice these exit status codes. + (merge 45a4f5d jk/difftool-command-not-found later to maint). + + * On Windows, help.browser configuration variable used to be ignored, + which has been corrected. + (merge 6db5967 js/no-html-bypass-on-windows later to maint). + + * The "git -c var[=val] cmd" facility to append a configuration + variable definition at the end of the search order was described in + git(1) manual page, but not in git-config(1), which was more likely + place for people to look for when they ask "can I make a one-shot + override, and if so how?" + (merge ae1f709 dg/document-git-c-in-git-config-doc later to maint). + + * The tempfile (hence its user lockfile) API lets the caller to open + a file descriptor to a temporary file, write into it and then + finalize it by first closing the filehandle and then either + removing or renaming the temporary file. When the process spawns a + subprocess after obtaining the file descriptor, and if the + subprocess has not exited when the attempt to remove or rename is + made, the last step fails on Windows, because the subprocess has + the file descriptor still open. Open tempfile with O_CLOEXEC flag + to avoid this (on Windows, this is mapped to O_NOINHERIT). + (merge 05d1ed6 bw/mingw-avoid-inheriting-fd-to-lockfile later to maint). + + * Correct an age-old calco (is that a typo-like word for calc) + in the documentation. + (merge 7841c48 ls/packet-line-protocol-doc-fix later to maint). + + * Other minor clean-ups and documentation updates + (merge 02a8cfa rs/merge-add-strategies-simplification later to maint). + (merge af4941d rs/merge-recursive-string-list-init later to maint). + (merge 1eb47f1 rs/use-strbuf-add-unique-abbrev later to maint). + (merge ddd0bfa jk/tighten-alloc later to maint). + (merge ecf30b2 rs/mailinfo-lib later to maint). + (merge 0eb75ce sg/reflog-past-root later to maint). + (merge 4369523 hv/doc-commit-reference-style later to maint). diff --git a/Documentation/RelNotes/2.10.1.txt b/Documentation/RelNotes/2.10.1.txt new file mode 100644 index 00000000000000..70462f7f7e9bed --- /dev/null +++ b/Documentation/RelNotes/2.10.1.txt @@ -0,0 +1,131 @@ +Git v2.10.1 Release Notes +========================= + +Fixes since v2.10 +----------------- + + * Clarify various ways to specify the "revision ranges" in the + documentation. + + * "diff-highlight" script (in contrib/) learned to work better with + "git log -p --graph" output. + + * The test framework left the number of tests and success/failure + count in the t/test-results directory, keyed by the name of the + test script plus the process ID. The latter however turned out not + to serve any useful purpose. The process ID part of the filename + has been removed. + + * Having a submodule whose ".git" repository is somehow corrupt + caused a few commands that recurse into submodules loop forever. + + * "git symbolic-ref -d HEAD" happily removes the symbolic ref, but + the resulting repository becomes an invalid one. Teach the command + to forbid removal of HEAD. + + * A test spawned a short-lived background process, which sometimes + prevented the test directory from getting removed at the end of the + script on some platforms. + + * Update a few tests that used to use GIT_CURL_VERBOSE to use the + newer GIT_TRACE_CURL. + + * Update Japanese translation for "git-gui". + + * "git fetch http::/site/path" did not die correctly and segfaulted + instead. + + * "git commit-tree" stopped reading commit.gpgsign configuration + variable that was meant for Porcelain "git commit" in Git 2.9; we + forgot to update "git gui" to look at the configuration to match + this change. + + * "git log --cherry-pick" used to include merge commits as candidates + to be matched up with other commits, resulting a lot of wasted time. + The patch-id generation logic has been updated to ignore merges to + avoid the wastage. + + * The http transport (with curl-multi option, which is the default + these days) failed to remove curl-easy handle from a curlm session, + which led to unnecessary API failures. + + * "git diff -W" output needs to extend the context backward to + include the header line of the current function and also forward to + include the body of the entire current function up to the header + line of the next one. This process may have to merge to adjacent + hunks, but the code forgot to do so in some cases. + + * Performance tests done via "t/perf" did not use the same set of + build configuration if the user relied on autoconf generated + configuration. + + * "git format-patch --base=..." feature that was recently added + showed the base commit information after "-- " e-mail signature + line, which turned out to be inconvenient. The base information + has been moved above the signature line. + + * Even when "git pull --rebase=preserve" (and the underlying "git + rebase --preserve") can complete without creating any new commit + (i.e. fast-forwards), it still insisted on having a usable ident + information (read: user.email is set correctly), which was less + than nice. As the underlying commands used inside "git rebase" + would fail with a more meaningful error message and advice text + when the bogus ident matters, this extra check was removed. + + * "git gc --aggressive" used to limit the delta-chain length to 250, + which is way too deep for gaining additional space savings and is + detrimental for runtime performance. The limit has been reduced to + 50. + + * Documentation for individual configuration variables to control use + of color (like `color.grep`) said that their default value is + 'false', instead of saying their default is taken from `color.ui`. + When we updated the default value for color.ui from 'false' to + 'auto' quite a while ago, all of them broke. This has been + corrected. + + * A shell script example in check-ref-format documentation has been + fixed. + + * "git checkout " does not follow the usual disambiguation + rules when the can be both a rev and a path, to allow + checking out a branch 'foo' in a project that happens to have a + file 'foo' in the working tree without having to disambiguate. + This was poorly documented and the check was incorrect when the + command was run from a subdirectory. + + * Some codepaths in "git diff" used regexec(3) on a buffer that was + mmap(2)ed, which may not have a terminating NUL, leading to a read + beyond the end of the mapped region. This was fixed by introducing + a regexec_buf() helper that takes a pair with REG_STARTEND + extension. + + * The procedure to build Git on Mac OS X for Travis CI hardcoded the + internal directory structure we assumed HomeBrew uses, which was a + no-no. The procedure has been updated to ask HomeBrew things we + need to know to fix this. + + * When "git rebase -i" is given a broken instruction, it told the + user to fix it with "--edit-todo", but didn't say what the step + after that was (i.e. "--continue"). + + * "git add --chmod=+x" added recently lacked documentation, which has + been corrected. + + * "git add --chmod=+x " added recently only toggled the + executable bit for paths that are either new or modified. This has + been corrected to flip the executable bit for all paths that match + the given pathspec. + + * "git pack-objects --include-tag" was taught that when we know that + we are sending an object C, we want a tag B that directly points at + C but also a tag A that points at the tag B. We used to miss the + intermediate tag B in some cases. + + * Documentation around tools to import from CVS was fairly outdated. + + * In the codepath that comes up with the hostname to be used in an + e-mail when the user didn't tell us, we looked at ai_canonname + field in struct addrinfo without making sure it is not NULL first. + +Also contains minor documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.10.2.txt b/Documentation/RelNotes/2.10.2.txt new file mode 100644 index 00000000000000..abbd331508a5ef --- /dev/null +++ b/Documentation/RelNotes/2.10.2.txt @@ -0,0 +1,111 @@ +Git v2.10.2 Release Notes +========================= + +Fixes since v2.10.1 +------------------- + + * The code that parses the format parameter of for-each-ref command + has seen a micro-optimization. + + * The "graph" API used in "git log --graph" miscounted the number of + output columns consumed so far when drawing a padding line, which + has been fixed; this did not affect any existing code as nobody + tried to write anything after the padding on such a line, though. + + * Almost everybody uses DEFAULT_ABBREV to refer to the default + setting for the abbreviation, but "git blame" peeked into + underlying variable bypassing the macro for no good reason. + + * Doc update to clarify what "log -3 --reverse" does. + + * An author name, that spelled a backslash-quoted double quote in the + human readable part "My \"double quoted\" name", was not unquoted + correctly while applying a patch from a piece of e-mail. + + * The original command line syntax for "git merge", which was "git + merge HEAD ...", has been deprecated for quite some + time, and "git gui" was the last in-tree user of the syntax. This + is finally fixed, so that we can move forward with the deprecation. + + * Codepaths that read from an on-disk loose object were too loose in + validating what they are reading is a proper object file and + sometimes read past the data they read from the disk, which has + been corrected. H/t to Gustavo Grieco for reporting. + + * "git worktree", even though it used the default_abbrev setting that + ought to be affected by core.abbrev configuration variable, ignored + the variable setting. The command has been taught to read the + default set of configuration variables to correct this. + + * A low-level function verify_packfile() was meant to show errors + that were detected without dying itself, but under some conditions + it didn't and died instead, which has been fixed. + + * When "git fetch" tries to find where the history of the repository + it runs in has diverged from what the other side has, it has a + mechanism to avoid digging too deep into irrelevant side branches. + This however did not work well over the "smart-http" transport due + to a design bug, which has been fixed. + + * When we started cURL to talk to imap server when a new enough + version of cURL library is available, we forgot to explicitly add + imap(s):// before the destination. To some folks, that didn't work + and the library tried to make HTTP(s) requests instead. + + * The ./configure script generated from configure.ac was taught how + to detect support of SSL by libcurl better. + + * http.emptyauth configuration is a way to allow an empty username to + pass when attempting to authenticate using mechanisms like + Kerberos. We took an unspecified (NULL) username and sent ":" + (i.e. no username, no password) to CURLOPT_USERPWD, but did not do + the same when the username is explicitly set to an empty string. + + * "git clone" of a local repository can be done at the filesystem + level, but the codepath did not check errors while copying and + adjusting the file that lists alternate object stores. + + * Documentation for "git commit" was updated to clarify that "commit + -p " adds to the current contents of the index to come up + with what to commit. + + * A stray symbolic link in $GIT_DIR/refs/ directory could make name + resolution loop forever, which has been corrected. + + * The "submodule..path" stored in .gitmodules is never copied + to .git/config and such a key in .git/config has no meaning, but + the documentation described it and submodule..url next to + each other as if both belong to .git/config. This has been fixed. + + * Recent git allows submodule..branch to use a special token + "." instead of the branch name; the documentation has been updated + to describe it. + + * In a worktree connected to a repository elsewhere, created via "git + worktree", "git checkout" attempts to protect users from confusion + by refusing to check out a branch that is already checked out in + another worktree. However, this also prevented checking out a + branch, which is designated as the primary branch of a bare + repository, in a worktree that is connected to the bare + repository. The check has been corrected to allow it. + + * "git rebase" immediately after "git clone" failed to find the fork + point from the upstream. + + * When fetching from a remote that has many tags that are irrelevant + to branches we are following, we used to waste way too many cycles + when checking if the object pointed at by a tag (that we are not + going to fetch!) exists in our repository too carefully. + + * The Travis CI configuration we ship ran the tests with --verbose + option but this risks non-TAP output that happens to be "ok" to be + misinterpreted as TAP signalling a test that passed. This resulted + in unnecessary failure. This has been corrected by introducing a + new mode to run our tests in the test harness to send the verbose + output separately to the log file. + + * Some AsciiDoc formatter mishandles a displayed illustration with + tabs in it. Adjust a few of them in merge-base documentation to + work around them. + +Also contains minor documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.10.3.txt b/Documentation/RelNotes/2.10.3.txt new file mode 100644 index 00000000000000..ad6a01bf835140 --- /dev/null +++ b/Documentation/RelNotes/2.10.3.txt @@ -0,0 +1,55 @@ +Git v2.10.3 Release Notes +========================= + +Fixes since v2.10.2 +------------------- + + * Extract a small helper out of the function that reads the authors + script file "git am" internally uses. + This by itself is not useful until a second caller appears in the + future for "rebase -i" helper. + + * The command-line completion script (in contrib/) learned to + complete "git cmd ^mas" to complete the negative end of + reference to "git cmd ^master". + + * "git send-email" attempts to pick up valid e-mails from the + trailers, but people in real world write non-addresses there, like + "Cc: Stable # 4.8+", which broke the output depending + on the availability and vintage of Mail::Address perl module. + + * The code that we have used for the past 10+ years to cycle + 4-element ring buffers turns out to be not quite portable in + theoretical world. + + * "git daemon" used fixed-length buffers to turn URL to the + repository the client asked for into the server side directory + path, using snprintf() to avoid overflowing these buffers, but + allowed possibly truncated paths to the directory. This has been + tightened to reject such a request that causes overlong path to be + required to serve. + + * Recent update to git-sh-setup (a library of shell functions that + are used by our in-tree scripted Porcelain commands) included + another shell library git-sh-i18n without specifying where it is, + relying on the $PATH. This has been fixed to be more explicit by + prefixing $(git --exec-path) output in front. + + * Fix for a racy false-positive test failure. + + * Portability update and workaround for builds on recent Mac OS X. + + * Update to the test framework made in 2.9 timeframe broke running + the tests under valgrind, which has been fixed. + + * Improve the rule to convert "unsigned char [20]" into "struct + object_id *" in contrib/coccinelle/ + + * "git-shell" rejects a request to serve a repository whose name + begins with a dash, which makes it no longer possible to get it + confused into spawning service programs like "git-upload-pack" with + an option like "--help", which in turn would spawn an interactive + pager, instead of working with the repository user asked to access + (i.e. the one whose name is "--help"). + +Also contains minor documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.10.4.txt b/Documentation/RelNotes/2.10.4.txt new file mode 100644 index 00000000000000..ee8142ad244dad --- /dev/null +++ b/Documentation/RelNotes/2.10.4.txt @@ -0,0 +1,4 @@ +Git v2.10.4 Release Notes +========================= + +This release forward-ports the fix for "ssh://..." URL from Git v2.7.6 diff --git a/Documentation/RelNotes/2.10.5.txt b/Documentation/RelNotes/2.10.5.txt new file mode 100644 index 00000000000000..a498fd6fdc24ae --- /dev/null +++ b/Documentation/RelNotes/2.10.5.txt @@ -0,0 +1,17 @@ +Git v2.10.5 Release Notes +========================= + +Fixes since v2.10.4 +------------------- + + * "git cvsserver" no longer is invoked by "git daemon" by default, + as it is old and largely unmaintained. + + * Various Perl scripts did not use safe_pipe_capture() instead of + backticks, leaving them susceptible to end-user input. They have + been corrected. + +Credits go to joernchen for finding the +unsafe constructs in "git cvsserver", and to Jeff King at GitHub for +finding and fixing instances of the same issue in other scripts. + diff --git a/Documentation/RelNotes/2.11.0.txt b/Documentation/RelNotes/2.11.0.txt new file mode 100644 index 00000000000000..b7b7dd361ef0bc --- /dev/null +++ b/Documentation/RelNotes/2.11.0.txt @@ -0,0 +1,593 @@ +Git 2.11 Release Notes +====================== + +Backward compatibility notes. + + * An empty string used as a pathspec element has always meant + 'everything matches', but it is too easy to write a script that + finds a path to remove in $path and run 'git rm "$paht"' by + mistake (when the user meant to give "$path"), which ends up + removing everything. This release starts warning about the + use of an empty string that is used for 'everything matches' and + asks users to use a more explicit '.' for that instead. + + The hope is that existing users will not mind this change, and + eventually the warning can be turned into a hard error, upgrading + the deprecation into removal of this (mis)feature. + + * The historical argument order "git merge HEAD ..." + has been deprecated for quite some time, and will be removed in the + next release (not this one). + + * The default abbreviation length, which has historically been 7, now + scales as the repository grows, using the approximate number of + objects in the repository and a bit of math around the birthday + paradox. The logic suggests to use 12 hexdigits for the Linux + kernel, and 9 to 10 for Git itself. + + +Updates since v2.10 +------------------- + +UI, Workflows & Features + + * Comes with new version of git-gui, now at its 0.21.0 tag. + + * "git format-patch --cover-letter HEAD^" to format a single patch + with a separate cover letter now numbers the output as [PATCH 0/1] + and [PATCH 1/1] by default. + + * An incoming "git push" that attempts to push too many bytes can now + be rejected by setting a new configuration variable at the receiving + end. + + * "git nosuchcommand --help" said "No manual entry for gitnosuchcommand", + which was not intuitive, given that "git nosuchcommand" said "git: + 'nosuchcommand' is not a git command". + + * "git clone --recurse-submodules --reference $path $URL" is a way to + reduce network transfer cost by borrowing objects in an existing + $path repository when cloning the superproject from $URL; it + learned to also peek into $path for presence of corresponding + repositories of submodules and borrow objects from there when able. + + * The "git diff --submodule={short,log}" mechanism has been enhanced + to allow "--submodule=diff" to show the patch between the submodule + commits bound to the superproject. + + * Even though "git hash-objects", which is a tool to take an + on-filesystem data stream and put it into the Git object store, + can perform "outside-world-to-Git" conversions (e.g. + end-of-line conversions and application of the clean-filter), and + it has had this feature on by default from very early days, its reverse + operation "git cat-file", which takes an object from the Git object + store and externalizes it for consumption by the outside world, + lacked an equivalent mechanism to run the "Git-to-outside-world" + conversion. The command learned the "--filters" option to do so. + + * Output from "git diff" can be made easier to read by intelligently selecting + which lines are common and which lines are added/deleted + when the lines before and after the changed section + are the same. A command line option (--indent-heuristic) and a + configuration variable (diff.indentHeuristic) are added to help with the + experiment to find good heuristics. + + * In some projects, it is common to use "[RFC PATCH]" as the subject + prefix for a patch meant for discussion rather than application. A + new format-patch option "--rfc" is a short-hand for "--subject-prefix=RFC PATCH" + to help the participants of such projects. + + * "git add --chmod={+,-}x " only changed the + executable bit for paths that are either new or modified. This has + been corrected to change the executable bit for all paths that match + the given pathspec. + + * When "git format-patch --stdout" output is placed as an in-body + header and it uses RFC2822 header folding, "git am" fails to + put the header line back into a single logical line. The + underlying "git mailinfo" was taught to handle this properly. + + * "gitweb" can spawn "highlight" to show blob contents with + (programming) language-specific syntax highlighting, but only + when the language is known. "highlight" can however be told + to guess the language itself by giving it "--force" option, which + has been enabled. + + * "git gui" l10n to Portuguese. + + * When given an abbreviated object name that is not (or more + realistically, "no longer") unique, we gave a fatal error + "ambiguous argument". This error is now accompanied by a hint that + lists the objects beginning with the given prefix. During the + course of development of this new feature, numerous minor bugs were + uncovered and corrected, the most notable one of which is that we + gave "short SHA1 xxxx is ambiguous." twice without good reason. + + * "git log rev^..rev" is an often-used revision range specification + to show what was done on a side branch merged at rev. This has + gained a short-hand "rev^-1". In general "rev^-$n" is the same as + "^rev^$n rev", i.e. what has happened on other branches while the + history leading to nth parent was looking the other way. + + * In recent versions of cURL, GSSAPI credential delegation is + disabled by default due to CVE-2011-2192; introduce a http.delegation + configuration variable to selectively allow enabling this. + (merge 26a7b23429 ps/http-gssapi-cred-delegation later to maint). + + * "git mergetool" learned to honor "-O" to control the + order of paths to present to the end user. + + * "git diff/log --ws-error-highlight=" lacked the corresponding + configuration variable (diff.wsErrorHighlight) to set it by default. + + * "git ls-files" learned the "--recurse-submodules" option + to get a listing of tracked files across submodules (i.e. this + only works with the "--cached" option, not for listing untracked or + ignored files). This would be a useful tool to sit on the upstream + side of a pipe that is read with xargs to work on all working tree + files from the top-level superproject. + + * A new credential helper that talks via "libsecret" with + implementations of XDG Secret Service API has been added to + contrib/credential/. + + * The GPG verification status shown by the "%G?" pretty format specifier + was not rich enough to differentiate a signature made by an expired + key, a signature made by a revoked key, etc. New output letters + have been assigned to express them. + + * In addition to purely abbreviated commit object names, "gitweb" + learned to turn "git describe" output (e.g. v2.9.3-599-g2376d31787) + into clickable links in its output. + + * "git commit" created an empty commit when invoked with an index + consisting solely of intend-to-add paths (added with "git add -N"). + It now requires the "--allow-empty" option to create such a commit. + The same logic prevented "git status" from showing such paths as "new files" in the + "Changes not staged for commit" section. + + * The smudge/clean filter API spawns an external process + to filter the contents of each path that has a filter defined. A + new type of "process" filter API has been added to allow the first + request to run the filter for a path to spawn a single process, and + all filtering is served by this single process for multiple + paths, reducing the process creation overhead. + + * The user always has to say "stash@{$N}" when naming a single + element in the default location of the stash, i.e. reflogs in + refs/stash. The "git stash" command learned to accept "git stash + apply 4" as a short-hand for "git stash apply stash@{4}". + + +Performance, Internal Implementation, Development Support etc. + + * The delta-base-cache mechanism has been a key to the performance in + a repository with a tightly packed packfile, but it did not scale + well even with a larger value of core.deltaBaseCacheLimit. + + * Enhance "git status --porcelain" output by collecting more data on + the state of the index and the working tree files, which may + further be used to teach git-prompt (in contrib/) to make fewer + calls to git. + + * Extract a small helper out of the function that reads the authors + script file "git am" internally uses. + (merge a77598e jc/am-read-author-file later to maint). + + * Lift calls to exit(2) and die() higher in the callchain in + sequencer.c files so that more helper functions in it can be used + by callers that want to handle error conditions themselves. + + * "git am" has been taught to make an internal call to "git apply"'s + innards without spawning the latter as a separate process. + + * The ref-store abstraction was introduced to the refs API so that we + can plug in different backends to store references. + + * The "unsigned char sha1[20]" to "struct object_id" conversion + continues. Notable changes in this round includes that ce->sha1, + i.e. the object name recorded in the cache_entry, turns into an + object_id. + + * JGit can show a fake ref "capabilities^{}" to "git fetch" when it + does not advertise any refs, but "git fetch" was not prepared to + see such an advertisement. When the other side disconnects without + giving any ref advertisement, we used to say "there may not be a + repository at that URL", but we may have seen other advertisements + like "shallow" and ".have" in which case we definitely know that a + repository is there. The code to detect this case has also been + updated. + + * Some codepaths in "git pack-objects" were not ready to use an + existing pack bitmap; now they are and as a result they have + become faster. + + * The codepath in "git fsck" to detect malformed tree objects has + been updated not to die but keep going after detecting them. + + * We call "qsort(array, nelem, sizeof(array[0]), fn)", and most of + the time third parameter is redundant. A new QSORT() macro lets us + omit it. + + * "git pack-objects" in a repository with many packfiles used to + spend a lot of time looking for/at objects in them; the accesses to + the packfiles are now optimized by checking the most-recently-used + packfile first. + (merge c9af708b1a jk/pack-objects-optim-mru later to maint). + + * Codepaths involved in interacting alternate object stores have + been cleaned up. + + * In order for the receiving end of "git push" to inspect the + received history and decide to reject the push, the objects sent + from the sending end need to be made available to the hook and + the mechanism for the connectivity check, and this was done + traditionally by storing the objects in the receiving repository + and letting "git gc" expire them. Instead, store the newly + received objects in a temporary area, and make them available by + reusing the alternate object store mechanism to them only while we + decide if we accept the check, and once we decide, either migrate + them to the repository or purge them immediately. + + * The require_clean_work_tree() helper was recreated in C when "git + pull" was rewritten from shell; the helper is now made available to + other callers in preparation for upcoming "rebase -i" work. + + * "git upload-pack" had its code cleaned-up and performance improved + by reducing use of timestamp-ordered commit-list, which was + replaced with a priority queue. + + * "git diff --no-index" codepath has been updated not to try to peek + into a .git/ directory that happens to be under the current + directory, when we know we are operating outside any repository. + + * Update of the sequencer codebase to make it reusable to reimplement + "rebase -i" continues. + + * Git generally does not explicitly close file descriptors that were + open in the parent process when spawning a child process, but most + of the time the child does not want to access them. As Windows does + not allow removing or renaming a file that has a file descriptor + open, a slow-to-exit child can even break the parent process by + holding onto them. Use O_CLOEXEC flag to open files in various + codepaths. + + * Update "interpret-trailers" machinery and teach it that people in + the real world write all sorts of cruft in the "trailer" that was + originally designed to have the neat-o "Mail-Header: like thing" + and nothing else. + + +Also contains various documentation updates and code clean-ups. + + +Fixes since v2.10 +----------------- + +Unless otherwise noted, all the fixes since v2.9 in the maintenance +track are contained in this release (see the maintenance releases' +notes for details). + + * Clarify various ways to specify the "revision ranges" in the + documentation. + + * "diff-highlight" script (in contrib/) learned to work better with + "git log -p --graph" output. + + * The test framework left the number of tests and success/failure + count in the t/test-results directory, keyed by the name of the + test script plus the process ID. The latter however turned out not + to serve any useful purpose. The process ID part of the filename + has been removed. + + * Having a submodule whose ".git" repository is somehow corrupt + caused a few commands that recurse into submodules to loop forever. + + * "git symbolic-ref -d HEAD" happily removes the symbolic ref, but + the resulting repository becomes an invalid one. Teach the command + to forbid removal of HEAD. + + * A test spawned a short-lived background process, which sometimes + prevented the test directory from getting removed at the end of the + script on some platforms. + + * Update a few tests that used to use GIT_CURL_VERBOSE to use the + newer GIT_TRACE_CURL. + + * "git pack-objects --include-tag" was taught that when we know that + we are sending an object C, we want a tag B that directly points at + C but also a tag A that points at the tag B. We used to miss the + intermediate tag B in some cases. + + * Update Japanese translation for "git-gui". + + * "git fetch http::/site/path" did not die correctly and segfaulted + instead. + + * "git commit-tree" stopped reading commit.gpgsign configuration + variable that was meant for Porcelain "git commit" in Git 2.9; we + forgot to update "git gui" to look at the configuration to match + this change. + + * "git add --chmod={+,-}x" added recently lacked documentation, which has + been corrected. + + * "git log --cherry-pick" used to include merge commits as candidates + to be matched up with other commits, resulting a lot of wasted time. + The patch-id generation logic has been updated to ignore merges and + avoid the wastage. + + * The http transport (with curl-multi option, which is the default + these days) failed to remove curl-easy handle from a curlm session, + which led to unnecessary API failures. + + * There were numerous corner cases in which the configuration files + are read and used or not read at all depending on the directory a + Git command was run, leading to inconsistent behaviour. The code + to set-up repository access at the beginning of a Git process has + been updated to fix them. + (merge 4d0efa1 jk/setup-sequence-update later to maint). + + * "git diff -W" output needs to extend the context backward to + include the header line of the current function and also forward to + include the body of the entire current function up to the header + line of the next one. This process may have to merge two adjacent + hunks, but the code forgot to do so in some cases. + + * Performance tests done via "t/perf" did not use the right + build configuration if the user relied on autoconf generated + configuration. + + * "git format-patch --base=..." feature that was recently added + showed the base commit information after the "-- " e-mail signature + line, which turned out to be inconvenient. The base information + has been moved above the signature line. + + * More i18n. + + * Even when "git pull --rebase=preserve" (and the underlying "git + rebase --preserve") can complete without creating any new commits + (i.e. fast-forwards), it still insisted on having usable ident + information (read: user.email is set correctly), which was less + than nice. As the underlying commands used inside "git rebase" + would fail with a more meaningful error message and advice text + when the bogus ident matters, this extra check was removed. + + * "git gc --aggressive" used to limit the delta-chain length to 250, + which is way too deep for gaining additional space savings and is + detrimental for runtime performance. The limit has been reduced to + 50. + + * Documentation for individual configuration variables to control use + of color (like `color.grep`) said that their default value is + 'false', instead of saying their default is taken from `color.ui`. + When we updated the default value for color.ui from 'false' to + 'auto' quite a while ago, all of them broke. This has been + corrected. + + * The pretty-format specifier "%C(auto)" used by the "log" family of + commands to enable coloring of the output is taught to also issue a + color-reset sequence to the output. + + * A shell script example in check-ref-format documentation has been + fixed. + + * "git checkout " does not follow the usual disambiguation + rules when the can be both a rev and a path, to allow + checking out a branch 'foo' in a project that happens to have a + file 'foo' in the working tree without having to disambiguate. + This was poorly documented and the check was incorrect when the + command was run from a subdirectory. + + * Some codepaths in "git diff" used regexec(3) on a buffer that was + mmap(2)ed, which may not have a terminating NUL, leading to a read + beyond the end of the mapped region. This was fixed by introducing + a regexec_buf() helper that takes a pair with REG_STARTEND + extension. + + * The procedure to build Git on Mac OS X for Travis CI hardcoded the + internal directory structure we assumed HomeBrew uses, which was a + no-no. The procedure has been updated to ask HomeBrew things we + need to know to fix this. + + * When "git rebase -i" is given a broken instruction, it told the + user to fix it with "--edit-todo", but didn't say what the step + after that was (i.e. "--continue"). + + * Documentation around tools to import from CVS was fairly outdated. + + * "git clone --recurse-submodules" lost the progress eye-candy in + a recent update, which has been corrected. + + * A low-level function verify_packfile() was meant to show errors + that were detected without dying itself, but under some conditions + it didn't and died instead, which has been fixed. + + * When "git fetch" tries to find where the history of the repository + it runs in has diverged from what the other side has, it has a + mechanism to avoid digging too deep into irrelevant side branches. + This however did not work well over the "smart-http" transport due + to a design bug, which has been fixed. + + * In the codepath that comes up with the hostname to be used in an + e-mail when the user didn't tell us, we looked at the ai_canonname + field in struct addrinfo without making sure it is not NULL first. + + * "git worktree", even though it used the default_abbrev setting that + ought to be affected by the core.abbrev configuration variable, ignored + the variable setting. The command has been taught to read the + default set of configuration variables to correct this. + + * "git init" tried to record core.worktree in the repository's + 'config' file when the GIT_WORK_TREE environment variable was set and + it was different from where GIT_DIR appears as ".git" at its top, + but the logic was faulty when .git is a "gitdir:" file that points + at the real place, causing trouble in working trees that are + managed by "git worktree". This has been corrected. + + * Codepaths that read from an on-disk loose object were too loose in + validating that they are reading a proper object file and + sometimes read past the data they read from the disk, which has + been corrected. H/t to Gustavo Grieco for reporting. + + * The original command line syntax for "git merge", which was "git + merge HEAD ...", has been deprecated for quite some + time, and "git gui" was the last in-tree user of the syntax. This + is finally fixed, so that we can move forward with the deprecation. + + * An author name that has a backslash-quoted double quote in the + human readable part ("My \"double quoted\" name"), was not unquoted + correctly while applying a patch from a piece of e-mail. + + * Doc update to clarify what "log -3 --reverse" does. + + * Almost everybody uses DEFAULT_ABBREV to refer to the default + setting for the abbreviation, but "git blame" peeked into + underlying variable bypassing the macro for no good reason. + + * The "graph" API used in "git log --graph" miscounted the number of + output columns consumed so far when drawing a padding line, which + has been fixed; this did not affect any existing code as nobody + tried to write anything after the padding on such a line, though. + + * The code that parses the format parameter of the for-each-ref command + has seen a micro-optimization. + + * When we started to use cURL to talk to an imap server, we forgot to explicitly add + imap(s):// before the destination. To some folks, that didn't work + and the library tried to make HTTP(s) requests instead. + + * The ./configure script generated from configure.ac was taught how + to detect support of SSL by libcurl better. + + * The command-line completion script (in contrib/) learned to + complete "git cmd ^mas" to complete the negative end of + reference to "git cmd ^master". + (merge 49416ad22a cp/completion-negative-refs later to maint). + + * The existing "git fetch --depth=" option was hard to use + correctly when making the history of an existing shallow clone + deeper. A new option, "--deepen=", has been added to make this + easier to use. "git clone" also learned "--shallow-since=" + and "--shallow-exclude=" options to make it easier to specify + "I am interested only in the recent N months worth of history" and + "Give me only the history since that version". + (merge cccf74e2da nd/shallow-deepen later to maint). + + * "git blame --reverse OLD path" is now DWIMmed to show how lines + in path in an old revision OLD have survived up to the current + commit. + (merge e1d09701a4 jc/blame-reverse later to maint). + + * The http.emptyauth configuration variable is a way to allow an empty username to + pass when attempting to authenticate using mechanisms like + Kerberos. We took an unspecified (NULL) username and sent ":" + (i.e. no username, no password) to CURLOPT_USERPWD, but did not do + the same when the username is explicitly set to an empty string. + + * "git clone" of a local repository can be done at the filesystem + level, but the codepath did not check errors while copying and + adjusting the file that lists alternate object stores. + + * Documentation for "git commit" was updated to clarify that "commit + -p " adds to the current contents of the index to come up + with what to commit. + + * A stray symbolic link in the $GIT_DIR/refs/ directory could make name + resolution loop forever, which has been corrected. + + * The "submodule..path" stored in .gitmodules is never copied + to .git/config and such a key in .git/config has no meaning, but + the documentation described it next to submodule..url + as if both belong to .git/config. This has been fixed. + + * In a worktree created via "git + worktree", "git checkout" attempts to protect users from confusion + by refusing to check out a branch that is already checked out in + another worktree. However, this also prevented checking out a + branch which is designated as the primary branch of a bare + repository, in a worktree that is connected to the bare + repository. The check has been corrected to allow it. + + * "git rebase" immediately after "git clone" failed to find the fork + point from the upstream. + + * When fetching from a remote that has many tags that are irrelevant + to branches we are following, we used to waste way too many cycles + checking if the object pointed at by a tag (that we are not + going to fetch!) exists in our repository too carefully. + + * Protect our code from over-eager compilers. + + * Recent git allows submodule..branch to use a special token + "." instead of the branch name; the documentation has been updated + to describe it. + + * "git send-email" attempts to pick up valid e-mails from the + trailers, but people in the real world write non-addresses there, like + "Cc: Stable # 4.8+", which broke the output depending + on the availability and vintage of the Mail::Address perl module. + (merge dcfafc5214 mm/send-email-cc-cruft-after-address later to maint). + + * The Travis CI configuration we ship ran the tests with the --verbose + option but this risks non-TAP output that happens to be "ok" to be + misinterpreted as TAP signalling a test that passed. This resulted + in unnecessary failures. This has been corrected by introducing a + new mode to run our tests in the test harness to send the verbose + output separately to the log file. + + * Some AsciiDoc formatters mishandle a displayed illustration with + tabs in it. Adjust a few of them in merge-base documentation to + work around them. + + * Fixed a minor regression in "git submodule" that was introduced + when more helper functions were reimplemented in C. + (merge 77b63ac31e sb/submodule-ignore-trailing-slash later to maint). + + * The code that we have used for the past 10+ years to cycle + 4-element ring buffers turns out to be not quite portable in + theoretical world. + (merge bb84735c80 rs/ring-buffer-wraparound later to maint). + + * "git daemon" used fixed-length buffers to turn URLs to the + repository the client asked for into the server side directory + paths, using snprintf() to avoid overflowing these buffers, but + allowed possibly truncated paths to the directory. This has been + tightened to reject such a request that causes an overlong path to be + served. + (merge 6bdb0083be jk/daemon-path-ok-check-truncation later to maint). + + * Recent update to git-sh-setup (a library of shell functions that + are used by our in-tree scripted Porcelain commands) included + another shell library git-sh-i18n without specifying where it is, + relying on the $PATH. This has been fixed to be more explicit by + prefixing with $(git --exec-path) output. + (merge 1073094f30 ak/sh-setup-dot-source-i18n-fix later to maint). + + * Fix for a racy false-positive test failure. + (merge fdf4f6c79b as/merge-attr-sleep later to maint). + + * Portability update and workaround for builds on recent Mac OS X. + (merge a296bc0132 ls/macos-update later to maint). + + * Using a %(HEAD) placeholder in "for-each-ref --format=" option + caused the command to segfault when on an unborn branch. + (merge 84679d470d jc/for-each-ref-head-segfault-fix later to maint). + + * "git rebase -i" did not work well with the core.commentchar + configuration variable for two reasons, both of which have been + fixed. + (merge 882cd23777 js/rebase-i-commentchar-fix later to maint). + + * Other minor doc, test and build updates and code cleanups. + (merge 5c238e29a8 jk/common-main later to maint). + (merge 5a5749e45b ak/pre-receive-hook-template-modefix later to maint). + (merge 6d834ac8f1 jk/rebase-config-insn-fmt-docfix later to maint). + (merge de9f7fa3b0 rs/commit-pptr-simplify later to maint). + (merge 4259d693fc sc/fmt-merge-msg-doc-markup-fix later to maint). + (merge 28fab7b23d nd/test-helpers later to maint). + (merge c2bb0c1d1e rs/cocci later to maint). + (merge 3285b7badb ps/common-info-doc later to maint). + (merge 2b090822e8 nd/worktree-lock later to maint). + (merge 4bd488ea7c jk/create-branch-remove-unused-param later to maint). + (merge 974e0044d6 tk/diffcore-delta-remove-unused later to maint). diff --git a/Documentation/RelNotes/2.11.1.txt b/Documentation/RelNotes/2.11.1.txt new file mode 100644 index 00000000000000..7d35cf186dbf76 --- /dev/null +++ b/Documentation/RelNotes/2.11.1.txt @@ -0,0 +1,168 @@ +Git v2.11.1 Release Notes +========================= + +Fixes since v2.11 +----------------- + + * The default Travis-CI configuration specifies newer P4 and GitLFS. + + * The character width table has been updated to match Unicode 9.0 + + * Update the isatty() emulation for Windows by updating the previous + hack that depended on internals of (older) MSVC runtime. + + * "git rev-parse --symbolic" failed with a more recent notation like + "HEAD^-1" and "HEAD^!". + + * An empty directory in a working tree that can simply be nuked used + to interfere while merging or cherry-picking a change to create a + submodule directory there, which has been fixed.. + + * The code in "git push" to compute if any commit being pushed in the + superproject binds a commit in a submodule that hasn't been pushed + out was overly inefficient, making it unusable even for a small + project that does not have any submodule but have a reasonable + number of refs. + + * "git push --dry-run --recurse-submodule=on-demand" wasn't + "--dry-run" in the submodules. + + * The output from "git worktree list" was made in readdir() order, + and was unstable. + + * mergetool..trustExitCode configuration variable did not apply + to built-in tools, but now it does. + + * "git p4" LFS support was broken when LFS stores an empty blob. + + * Fix a corner case in merge-recursive regression that crept in + during 2.10 development cycle. + + * Update the error messages from the dumb-http client when it fails + to obtain loose objects; we used to give sensible error message + only upon 404 but we now forbid unexpected redirects that needs to + be reported with something sensible. + + * When diff.renames configuration is on (and with Git 2.9 and later, + it is enabled by default, which made it worse), "git stash" + misbehaved if a file is removed and another file with a very + similar content is added. + + * "git diff --no-index" did not take "--no-abbrev" option. + + * "git difftool --dir-diff" had a minor regression when started from + a subdirectory, which has been fixed. + + * "git commit --allow-empty --only" (no pathspec) with dirty index + ought to be an acceptable way to create a new commit that does not + change any paths, but it was forbidden, perhaps because nobody + needed it so far. + + * A pathname that begins with "//" or "\\" on Windows is special but + path normalization logic was unaware of it. + + * "git pull --rebase", when there is no new commits on our side since + we forked from the upstream, should be able to fast-forward without + invoking "git rebase", but it didn't. + + * The way to specify hotkeys to "xxdiff" that is used by "git + mergetool" has been modernized to match recent versions of xxdiff. + + * Unlike "git am --abort", "git cherry-pick --abort" moved HEAD back + to where cherry-pick started while picking multiple changes, when + the cherry-pick stopped to ask for help from the user, and the user + did "git reset --hard" to a different commit in order to re-attempt + the operation. + + * Code cleanup in shallow boundary computation. + + * A recent update to receive-pack to make it easier to drop garbage + objects made it clear that GIT_ALTERNATE_OBJECT_DIRECTORIES cannot + have a pathname with a colon in it (no surprise!), and this in turn + made it impossible to push into a repository at such a path. This + has been fixed by introducing a quoting mechanism used when + appending such a path to the colon-separated list. + + * The function usage_msg_opt() has been updated to say "fatal:" + before the custom message programs give, when they want to die + with a message about wrong command line options followed by the + standard usage string. + + * "git index-pack --stdin" needs an access to an existing repository, + but "git index-pack file.pack" to generate an .idx file that + corresponds to a packfile does not. + + * Fix for NDEBUG builds. + + * A lazy "git push" without refspec did not internally use a fully + specified refspec to perform 'current', 'simple', or 'upstream' + push, causing unnecessary "ambiguous ref" errors. + + * "git p4" misbehaved when swapping a directory and a symbolic link. + + * Even though an fix was attempted in Git 2.9.3 days, but running + "git difftool --dir-diff" from a subdirectory never worked. This + has been fixed. + + * "git p4" that tracks multiple p4 paths imported a single changelist + that touches files in these multiple paths as one commit, followed + by many empty commits. This has been fixed. + + * A potential but unlikely buffer overflow in Windows port has been + fixed. + + * When the http server gives an incomplete response to a smart-http + rpc call, it could lead to client waiting for a full response that + will never come. Teach the client side to notice this condition + and abort the transfer. + + * Some platforms no longer understand "latin-1" that is still seen in + the wild in e-mail headers; replace them with "iso-8859-1" that is + more widely known when conversion fails from/to it. + + * Update the procedure to generate "tags" for developer support. + + * Update the definition of the MacOSX test environment used by + TravisCI. + + * A few git-svn updates. + + * Compression setting for producing packfiles were spread across + three codepaths, one of which did not honor any configuration. + Unify these so that all of them honor core.compression and + pack.compression variables the same way. + + * "git fast-import" sometimes mishandled while rebalancing notes + tree, which has been fixed. + + * Recent update to the default abbreviation length that auto-scales + lacked documentation update, which has been corrected. + + * Leakage of lockfiles in the config subsystem has been fixed. + + * It is natural that "git gc --auto" may not attempt to pack + everything into a single pack, and there is no point in warning + when the user has configured the system to use the pack bitmap, + leading to disabling further "gc". + + * "git archive" did not read the standard configuration files, and + failed to notice a file that is marked as binary via the userdiff + driver configuration. + + * "git blame --porcelain" misidentified the "previous" + pair (aka "source") when contents came from two or more files. + + * "git rebase -i" with a recent update started showing an incorrect + count when squashing more than 10 commits. + + * "git @{push}" on a detached HEAD used to segfault; it has + been corrected to error out with a message. + + * Tighten a test to avoid mistaking an extended ERE regexp engine as + a PRE regexp engine. + + * Typing ^C to pager, which usually does not kill it, killed Git and + took the pager down as a collateral damage in certain process-tree + structure. This has been fixed. + +Also contains various documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.11.2.txt b/Documentation/RelNotes/2.11.2.txt new file mode 100644 index 00000000000000..74288511686cb7 --- /dev/null +++ b/Documentation/RelNotes/2.11.2.txt @@ -0,0 +1,12 @@ +Git v2.11.2 Release Notes +========================= + +Fixes since v2.11.1 +------------------- + + * "git-shell" rejects a request to serve a repository whose name + begins with a dash, which makes it no longer possible to get it + confused into spawning service programs like "git-upload-pack" with + an option like "--help", which in turn would spawn an interactive + pager, instead of working with the repository user asked to access + (i.e. the one whose name is "--help"). diff --git a/Documentation/RelNotes/2.11.3.txt b/Documentation/RelNotes/2.11.3.txt new file mode 100644 index 00000000000000..4e3b78d0e8f97b --- /dev/null +++ b/Documentation/RelNotes/2.11.3.txt @@ -0,0 +1,4 @@ +Git v2.11.3 Release Notes +========================= + +This release forward-ports the fix for "ssh://..." URL from Git v2.7.6 diff --git a/Documentation/RelNotes/2.11.4.txt b/Documentation/RelNotes/2.11.4.txt new file mode 100644 index 00000000000000..ad4da8eb09ef5c --- /dev/null +++ b/Documentation/RelNotes/2.11.4.txt @@ -0,0 +1,17 @@ +Git v2.11.4 Release Notes +========================= + +Fixes since v2.11.3 +------------------- + + * "git cvsserver" no longer is invoked by "git daemon" by default, + as it is old and largely unmaintained. + + * Various Perl scripts did not use safe_pipe_capture() instead of + backticks, leaving them susceptible to end-user input. They have + been corrected. + +Credits go to joernchen for finding the +unsafe constructs in "git cvsserver", and to Jeff King at GitHub for +finding and fixing instances of the same issue in other scripts. + diff --git a/Documentation/RelNotes/2.12.0.txt b/Documentation/RelNotes/2.12.0.txt new file mode 100644 index 00000000000000..d2f6a836146d51 --- /dev/null +++ b/Documentation/RelNotes/2.12.0.txt @@ -0,0 +1,500 @@ +Git 2.12 Release Notes +====================== + +Backward compatibility notes. + + * Use of an empty string that is used for 'everything matches' is + still warned and Git asks users to use a more explicit '.' for that + instead. The hope is that existing users will not mind this + change, and eventually the warning can be turned into a hard error, + upgrading the deprecation into removal of this (mis)feature. That + is not scheduled to happen in the upcoming release (yet). + + * The historical argument order "git merge HEAD ..." + has been deprecated for quite some time, and will be removed in a + future release. + + * An ancient script "git relink" has been removed. + + +Updates since v2.11 +------------------- + +UI, Workflows & Features + + * Various updates to "git p4". + + * "git p4" didn't interact with the internal of .git directory + correctly in the modern "git-worktree"-enabled world. + + * "git branch --list" and friends learned "--ignore-case" option to + optionally sort branches and tags case insensitively. + + * In addition to %(subject), %(body), "log --pretty=format:..." + learned a new placeholder %(trailers). + + * "git rebase" learned "--quit" option, which allows a user to + remove the metadata left by an earlier "git rebase" that was + manually aborted without using "git rebase --abort". + + * "git clone --reference $there --recurse-submodules $super" has been + taught to guess repositories usable as references for submodules of + $super that are embedded in $there while making a clone of the + superproject borrow objects from $there; extend the mechanism to + also allow submodules of these submodules to borrow repositories + embedded in these clones of the submodules embedded in the clone of + the superproject. + + * Porcelain scripts written in Perl are getting internationalized. + + * "git merge --continue" has been added as a synonym to "git commit" + to conclude a merge that has stopped due to conflicts. + + * Finer-grained control of what protocols are allowed for transports + during clone/fetch/push have been enabled via a new configuration + mechanism. + + * "git shortlog" learned "--committer" option to group commits by + committer, instead of author. + + * GitLFS integration with "git p4" has been updated. + + * The isatty() emulation for Windows has been updated to eradicate + the previous hack that depended on internals of (older) MSVC + runtime. + + * Some platforms no longer understand "latin-1" that is still seen in + the wild in e-mail headers; replace them with "iso-8859-1" that is + more widely known when conversion fails from/to it. + + * "git grep" has been taught to optionally recurse into submodules. + + * "git rm" used to refuse to remove a submodule when it has its own + git repository embedded in its working tree. It learned to move + the repository away to $GIT_DIR/modules/ of the superproject + instead, and allow the submodule to be deleted (as long as there + will be no loss of local modifications, that is). + + * A recent updates to "git p4" was not usable for older p4 but it + could be made to work with minimum changes. Do so. + + * "git diff" learned diff.interHunkContext configuration variable + that gives the default value for its --inter-hunk-context option. + + * The prereleaseSuffix feature of version comparison that is used in + "git tag -l" did not correctly when two or more prereleases for the + same release were present (e.g. when 2.0, 2.0-beta1, and 2.0-beta2 + are there and the code needs to compare 2.0-beta1 and 2.0-beta2). + + * "git submodule push" learned "--recurse-submodules=only option to + push submodules out without pushing the top-level superproject. + + * "git tag" and "git verify-tag" learned to put GPG verification + status in their "--format=" output format. + + * An ancient repository conversion tool left in contrib/ has been + removed. + + * "git show-ref HEAD" used with "--verify" because the user is not + interested in seeing refs/remotes/origin/HEAD, and used with + "--head" because the user does not want HEAD to be filtered out, + i.e. "git show-ref --head --verify HEAD", did not work as expected. + + * "git submodule add" used to be confused and refused to add a + locally created repository; users can now use "--force" option + to add them. + (merge 619acfc78c sb/submodule-add-force later to maint). + + * Some people feel the default set of colors used by "git log --graph" + rather limiting. A mechanism to customize the set of colors has + been introduced. + + * "git read-tree" and its underlying unpack_trees() machinery learned + to report problematic paths prefixed with the --super-prefix option. + + * When a submodule "A", which has another submodule "B" nested within + it, is "absorbed" into the top-level superproject, the inner + submodule "B" used to be left in a strange state. The logic to + adjust the .git pointers in these submodules has been corrected. + + * The user can specify a custom update method that is run when + "submodule update" updates an already checked out submodule. This + was ignored when checking the submodule out for the first time and + we instead always just checked out the commit that is bound to the + path in the superproject's index. + + * The command line completion (in contrib/) learned that + "git diff --submodule=" can take "diff" as a recently added option. + + * The "core.logAllRefUpdates" that used to be boolean has been + enhanced to take 'always' as well, to record ref updates to refs + other than the ones that are expected to be updated (i.e. branches, + remote-tracking branches and notes). + + * Comes with more command line completion (in contrib/) for recently + introduced options. + + +Performance, Internal Implementation, Development Support etc. + + * Commands that operate on a log message and add lines to the trailer + blocks, such as "format-patch -s", "cherry-pick (-x|-s)", and + "commit -s", have been taught to use the logic of and share the + code with "git interpret-trailer". + + * The default Travis-CI configuration specifies newer P4 and GitLFS. + + * The "fast hash" that had disastrous performance issues in some + corner cases has been retired from the internal diff. + + * The character width table has been updated to match Unicode 9.0 + + * Update the procedure to generate "tags" for developer support. + + * The codeflow of setting NOATIME and CLOEXEC on file descriptors Git + opens has been simplified. + + * "git diff" and its family had two experimental heuristics to shift + the contents of a hunk to make the patch easier to read. One of + them turns out to be better than the other, so leave only the + "--indent-heuristic" option and remove the other one. + + * A new submodule helper "git submodule embedgitdirs" to make it + easier to move embedded .git/ directory for submodules in a + superproject to .git/modules/ (and point the latter with the former + that is turned into a "gitdir:" file) has been added. + + * "git push \\server\share\dir" has recently regressed and then + fixed. A test has retroactively been added for this breakage. + + * Build updates for Cygwin. + + * The implementation of "real_path()" was to go there with chdir(2) + and call getcwd(3), but this obviously wouldn't be usable in a + threaded environment. Rewrite it to manually resolve relative + paths including symbolic links in path components. + + * Adjust documentation to help AsciiDoctor render better while not + breaking the rendering done by AsciiDoc. + + * The sequencer machinery has been further enhanced so that a later + set of patches can start using it to reimplement "rebase -i". + + * Update the definition of the MacOSX test environment used by + TravisCI. + + * Rewrite a scripted porcelain "git difftool" in C. + + * "make -C t failed" will now run only the tests that failed in the + previous run. This is usable only when prove is not use, and gives + a useless error message when run after "make clean", but otherwise + is serviceable. + + * "uchar [40]" to "struct object_id" conversion continues. + + +Also contains various documentation updates and code clean-ups. + +Fixes since v2.10 +----------------- + +Unless otherwise noted, all the fixes since v2.9 in the maintenance +track are contained in this release (see the maintenance releases' +notes for details). + + * We often decide if a session is interactive by checking if the + standard I/O streams are connected to a TTY, but isatty() that + comes with Windows incorrectly returned true if it is used on NUL + (i.e. an equivalent to /dev/null). This has been fixed. + + * "git svn" did not work well with path components that are "0", and + some configuration variable it uses were not documented. + + * "git rev-parse --symbolic" failed with a more recent notation like + "HEAD^-1" and "HEAD^!". + + * An empty directory in a working tree that can simply be nuked used + to interfere while merging or cherry-picking a change to create a + submodule directory there, which has been fixed.. + + * The code in "git push" to compute if any commit being pushed in the + superproject binds a commit in a submodule that hasn't been pushed + out was overly inefficient, making it unusable even for a small + project that does not have any submodule but have a reasonable + number of refs. + + * "git push --dry-run --recurse-submodule=on-demand" wasn't + "--dry-run" in the submodules. + + * The output from "git worktree list" was made in readdir() order, + and was unstable. + + * mergetool..trustExitCode configuration variable did not apply + to built-in tools, but now it does. + + * "git p4" LFS support was broken when LFS stores an empty blob. + + * A corner case in merge-recursive regression that crept in + during 2.10 development cycle has been fixed. + + * Transport with dumb http can be fooled into following foreign URLs + that the end user does not intend to, especially with the server + side redirects and http-alternates mechanism, which can lead to + security issues. Tighten the redirection and make it more obvious + to the end user when it happens. + + * Update the error messages from the dumb-http client when it fails + to obtain loose objects; we used to give sensible error message + only upon 404 but we now forbid unexpected redirects that needs to + be reported with something sensible. + + * When diff.renames configuration is on (and with Git 2.9 and later, + it is enabled by default, which made it worse), "git stash" + misbehaved if a file is removed and another file with a very + similar content is added. + + * "git diff --no-index" did not take "--no-abbrev" option. + + * "git difftool --dir-diff" had a minor regression when started from + a subdirectory, which has been fixed. + + * "git commit --allow-empty --only" (no pathspec) with dirty index + ought to be an acceptable way to create a new commit that does not + change any paths, but it was forbidden, perhaps because nobody + needed it so far. + + * Git 2.11 had a minor regression in "merge --ff-only" that competed + with another process that simultaneously attempted to update the + index. We used to explain what went wrong with an error message, + but the new code silently failed. The error message has been + resurrected. + + * A pathname that begins with "//" or "\\" on Windows is special but + path normalization logic was unaware of it. + + * "git pull --rebase", when there is no new commits on our side since + we forked from the upstream, should be able to fast-forward without + invoking "git rebase", but it didn't. + + * The way to specify hotkeys to "xxdiff" that is used by "git + mergetool" has been modernized to match recent versions of xxdiff. + + * Unlike "git am --abort", "git cherry-pick --abort" moved HEAD back + to where cherry-pick started while picking multiple changes, when + the cherry-pick stopped to ask for help from the user, and the user + did "git reset --hard" to a different commit in order to re-attempt + the operation. + + * Code cleanup in shallow boundary computation. + + * A recent update to receive-pack to make it easier to drop garbage + objects made it clear that GIT_ALTERNATE_OBJECT_DIRECTORIES cannot + have a pathname with a colon in it (no surprise!), and this in turn + made it impossible to push into a repository at such a path. This + has been fixed by introducing a quoting mechanism used when + appending such a path to the colon-separated list. + + * The function usage_msg_opt() has been updated to say "fatal:" + before the custom message programs give, when they want to die + with a message about wrong command line options followed by the + standard usage string. + + * "git index-pack --stdin" needs an access to an existing repository, + but "git index-pack file.pack" to generate an .idx file that + corresponds to a packfile does not. + + * Fix for NDEBUG builds. + + * A lazy "git push" without refspec did not internally use a fully + specified refspec to perform 'current', 'simple', or 'upstream' + push, causing unnecessary "ambiguous ref" errors. + + * "git p4" misbehaved when swapping a directory and a symbolic link. + + * Even though an fix was attempted in Git 2.9.3 days, but running + "git difftool --dir-diff" from a subdirectory never worked. This + has been fixed. + + * "git p4" that tracks multiple p4 paths imported a single changelist + that touches files in these multiple paths as one commit, followed + by many empty commits. This has been fixed. + + * A potential but unlikely buffer overflow in Windows port has been + fixed. + + * When the http server gives an incomplete response to a smart-http + rpc call, it could lead to client waiting for a full response that + will never come. Teach the client side to notice this condition + and abort the transfer. + + * Compression setting for producing packfiles were spread across + three codepaths, one of which did not honor any configuration. + Unify these so that all of them honor core.compression and + pack.compression variables the same way. + + * "git fast-import" sometimes mishandled while rebalancing notes + tree, which has been fixed. + + * Recent update to the default abbreviation length that auto-scales + lacked documentation update, which has been corrected. + + * Leakage of lockfiles in the config subsystem has been fixed. + + * It is natural that "git gc --auto" may not attempt to pack + everything into a single pack, and there is no point in warning + when the user has configured the system to use the pack bitmap, + leading to disabling further "gc". + + * "git archive" did not read the standard configuration files, and + failed to notice a file that is marked as binary via the userdiff + driver configuration. + + * "git blame --porcelain" misidentified the "previous" + pair (aka "source") when contents came from two or more files. + + * "git rebase -i" with a recent update started showing an incorrect + count when squashing more than 10 commits. + + * "git @{push}" on a detached HEAD used to segfault; it has + been corrected to error out with a message. + + * Running "git add a/b" when "a" is a submodule correctly errored + out, but without a meaningful error message. + (merge 2d81c48fa7 sb/pathspec-errors later to maint). + + * Typing ^C to pager, which usually does not kill it, killed Git and + took the pager down as a collateral damage in certain process-tree + structure. This has been fixed. + + * "git mergetool" without any pathspec on the command line that is + run from a subdirectory became no-op in Git v2.11 by mistake, which + has been fixed. + + * Retire long unused/unmaintained gitview from the contrib/ area. + (merge 3120925c25 sb/remove-gitview later to maint). + + * Tighten a test to avoid mistaking an extended ERE regexp engine as + a PRE regexp engine. + + * An error message with an ASCII control character like '\r' in it + can alter the message to hide its early part, which is problematic + when a remote side gives such an error message that the local side + will relay with a "remote: " prefix. + (merge f290089879 jk/vreport-sanitize later to maint). + + * "git fsck" inspects loose objects more carefully now. + (merge cce044df7f jk/loose-object-fsck later to maint). + + * A crashing bug introduced in v2.11 timeframe has been found (it is + triggerable only in fast-import) and fixed. + (merge abd5a00268 jk/clear-delta-base-cache-fix later to maint). + + * With an anticipatory tweak for remotes defined in ~/.gitconfig + (e.g. "remote.origin.prune" set to true, even though there may or + may not actually be "origin" remote defined in a particular Git + repository), "git remote rename" and other commands misinterpreted + and behaved as if such a non-existing remote actually existed. + (merge e459b073fb js/remote-rename-with-half-configured-remote later to maint). + + * A few codepaths had to rely on a global variable when sorting + elements of an array because sort(3) API does not allow extra data + to be passed to the comparison function. Use qsort_s() when + natively available, and a fallback implementation of it when not, + to eliminate the need, which is a prerequisite for making the + codepath reentrant. + + * "git fsck --connectivity-check" was not working at all. + (merge a2b22854bd jk/fsck-connectivity-check-fix later to maint). + + * After starting "git rebase -i", which first opens the user's editor + to edit the series of patches to apply, but before saving the + contents of that file, "git status" failed to show the current + state (i.e. you are in an interactive rebase session, but you have + applied no steps yet) correctly. + (merge df9ded4984 js/status-pre-rebase-i later to maint). + + * Test tweak for FreeBSD where /usr/bin/unzip is unsuitable to run + our tests but /usr/local/bin/unzip is usable. + (merge d98b2c5fce js/unzip-in-usr-bin-workaround later to maint). + + * "git p4" did not work well with multiple git-p4.mapUser entries on + Windows. + (merge c3c2b05776 gv/mingw-p4-mapuser later to maint). + + * "git help" enumerates executable files in $PATH; the implementation + of "is this file executable?" on Windows has been optimized. + (merge c755015f79 hv/mingw-help-is-executable later to maint). + + * Test tweaks for those who have default ACL in their git source tree + that interfere with the umask test. + (merge d549d21307 mm/reset-facl-before-umask-test later to maint). + + * Names of the various hook scripts must be spelled exactly, but on + Windows, an .exe binary must be named with .exe suffix; notice + $GIT_DIR/hooks/.exe as a valid hook. + (merge 235be51fbe js/mingw-hooks-with-exe-suffix later to maint). + + * Asciidoctor, an alternative reimplementation of AsciiDoc, still + needs some changes to work with documents meant to be formatted + with AsciiDoc. "make USE_ASCIIDOCTOR=YesPlease" to use it out of + the box to document our pages is getting closer to reality. + + * Correct command line completion (in contrib/) on "git svn" + (merge 2cbad17642 ew/complete-svn-authorship-options later to maint). + + * Incorrect usage help message for "git worktree prune" has been fixed. + (merge 2488dcab22 ps/worktree-prune-help-fix later to maint). + + * Adjust a perf test to new world order where commands that do + require a repository are really strict about having a repository. + (merge c86000c1a7 rs/p5302-create-repositories-before-tests later to maint). + + * "git log --graph" did not work well with "--name-only", even though + other forms of "diff" output were handled correctly. + (merge f5022b5fed jk/log-graph-name-only later to maint). + + * The push-options given via the "--push-options" option were not + passed through to external remote helpers such as "smart HTTP" that + are invoked via the transport helper. + + * The documentation explained what "git stash" does to the working + tree (after stashing away the local changes) in terms of "reset + --hard", which was exposing an unnecessary implementation detail. + (merge 20a7e06172 tg/stash-doc-cleanup later to maint). + + * When "git p4" imports changelist that removes paths, it failed to + convert pathnames when the p4 used encoding different from the one + used on the Git side. This has been corrected. + (merge a8b05162e8 ls/p4-path-encoding later to maint). + + * A new coccinelle rule that catches a check of !pointer before the + pointer is free(3)d, which most likely is a bug. + (merge ec6cd14c7a rs/cocci-check-free-only-null later to maint). + + * "ls-files" run with pathspec has been micro-optimized to avoid + having to memmove(3) unnecessary bytes. + (merge 96f6d3f61a rs/ls-files-partial-optim later to maint). + + * A hotfix for a topic already in 'master'. + (merge a4d92d579f js/mingw-isatty later to maint). + + * Other minor doc, test and build updates and code cleanups. + (merge f2627d9b19 sb/submodule-config-cleanup later to maint). + (merge 384f1a167b sb/unpack-trees-cleanup later to maint). + (merge 874444b704 rh/diff-orderfile-doc later to maint). + (merge eafd5d9483 cw/doc-sign-off later to maint). + (merge 0aaad415bc rs/absolute-pathdup later to maint). + (merge 4432dd6b5b rs/receive-pack-cleanup later to maint). + (merge 540a398e9c sg/mailmap-self later to maint). + (merge 209df269a6 nd/rev-list-all-includes-HEAD-doc later to maint). + (merge 941b9c5270 sb/doc-unify-bottom later to maint). + (merge 2aaf37b62c jk/doc-remote-helpers-markup-fix later to maint). + (merge e91461b332 jk/doc-submodule-markup-fix later to maint). + (merge 8ab9740d9f dp/submodule-doc-markup-fix later to maint). + (merge 0838cbc22f jk/tempfile-ferror-fclose-confusion later to maint). + (merge 115a40add6 dr/doc-check-ref-format-normalize later to maint). + (merge 133f0a299d gp/document-dotfiles-in-templates-are-not-copied later to maint). + (merge 2b35a9f4c7 bc/blame-doc-fix later to maint). + (merge 7e82388024 ps/doc-gc-aggressive-depth-update later to maint). + (merge 9993a7c5f1 bc/worktree-doc-fix-detached later to maint). + (merge e519eccdf4 rt/align-add-i-help-text later to maint). diff --git a/Documentation/RelNotes/2.12.1.txt b/Documentation/RelNotes/2.12.1.txt new file mode 100644 index 00000000000000..a74f7db747670e --- /dev/null +++ b/Documentation/RelNotes/2.12.1.txt @@ -0,0 +1,41 @@ +Git v2.12.1 Release Notes +========================= + +Fixes since v2.12 +----------------- + + * Reduce authentication round-trip over HTTP when the server supports + just a single authentication method. This also improves the + behaviour when Git is misconfigured to enable http.emptyAuth + against a server that does not authenticate without a username + (i.e. not using Kerberos etc., which makes http.emptyAuth + pointless). + + * Windows port wants to use OpenSSL's implementation of SHA-1 + routines, so let them. + + * Add 32-bit Linux variant to the set of platforms to be tested with + Travis CI. + + * When a redirected http transport gets an error during the + redirected request, we ignored the error we got from the server, + and ended up giving a not-so-useful error message. + + * The patch subcommand of "git add -i" was meant to have paths + selection prompt just like other subcommand, unlike "git add -p" + directly jumps to hunk selection. Recently, this was broken and + "add -i" lost the paths selection dialog, but it now has been + fixed. + + * Git v2.12 was shipped with an embarrassing breakage where various + operations that verify paths given from the user stopped dying when + seeing an issue, and instead later triggering segfault. + + * The code to parse "git log -L..." command line was buggy when there + are many ranges specified with -L; overrun of the allocated buffer + has been fixed. + + * The command-line parsing of "git log -L" copied internal data + structures using incorrect size on ILP32 systems. + +Also contains various documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.12.2.txt b/Documentation/RelNotes/2.12.2.txt new file mode 100644 index 00000000000000..441939709c777a --- /dev/null +++ b/Documentation/RelNotes/2.12.2.txt @@ -0,0 +1,83 @@ +Git v2.12.2 Release Notes +========================= + +Fixes since v2.12.1 +------------------- + + * "git status --porcelain" is supposed to give a stable output, but a + few strings were left as translatable by mistake. + + * "Dumb http" transport used to misparse a nonsense http-alternates + response, which has been fixed. + + * "git diff --quiet" relies on the size field in diff_filespec to be + correctly populated, but diff_populate_filespec() helper function + made an incorrect short-cut when asked only to populate the size + field for paths that need to go through convert_to_git() (e.g. CRLF + conversion). + + * There is no need for Python only to give a few messages to the + standard error stream, but we somehow did. + + * A leak in a codepath to read from a packed object in (rare) cases + has been plugged. + + * "git upload-pack", which is a counter-part of "git fetch", did not + report a request for a ref that was not advertised as invalid. + This is generally not a problem (because "git fetch" will stop + before making such a request), but is the right thing to do. + + * A "gc.log" file left by a backgrounded "gc --auto" disables further + automatic gc; it has been taught to run at least once a day (by + default) by ignoring a stale "gc.log" file that is too old. + + * "git remote rm X", when a branch has remote X configured as the + value of its branch.*.remote, tried to remove branch.*.remote and + branch.*.merge and failed if either is unset. + + * A caller of tempfile API that uses stdio interface to write to + files may ignore errors while writing, which is detected when + tempfile is closed (with a call to ferror()). By that time, the + original errno that may have told us what went wrong is likely to + be long gone and was overwritten by an irrelevant value. + close_tempfile() now resets errno to EIO to make errno at least + predictable. + + * "git show-branch" expected there were only very short branch names + in the repository and used a fixed-length buffer to hold them + without checking for overflow. + + * The code that parses header fields in the commit object has been + updated for (micro)performance and code hygiene. + + * A test that creates a confusing branch whose name is HEAD has been + corrected not to do so. + + * "Cc:" on the trailer part does not have to conform to RFC strictly, + unlike in the e-mail header. "git send-email" has been updated to + ignore anything after '>' when picking addresses, to allow non-address + cruft like " # stable 4.4" after the address. + + * "git push" had a handful of codepaths that could lead to a deadlock + when unexpected error happened, which has been fixed. + + * Code to read submodule..ignore config did not state the + variable name correctly when giving an error message diagnosing + misconfiguration. + + * "git ls-remote" and "git archive --remote" are designed to work + without being in a directory under Git's control. However, recent + updates revealed that we randomly look into a directory called + .git/ without actually doing necessary set-up when working in a + repository. Stop doing so. + + * The code to parse the command line "git grep ... + [[--] ...]" has been cleaned up, and a handful of bugs + have been fixed (e.g. we used to check "--" if it is a rev). + + * The code to parse "git -c VAR=VAL cmd" and set configuration + variable for the duration of cmd had two small bugs, which have + been fixed. + This supersedes jc/config-case-cmdline topic that has been discarded. + +Also contains various documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.12.3.txt b/Documentation/RelNotes/2.12.3.txt new file mode 100644 index 00000000000000..ebca846d5d8021 --- /dev/null +++ b/Documentation/RelNotes/2.12.3.txt @@ -0,0 +1,64 @@ +Git v2.12.3 Release Notes +========================= + +Fixes since v2.12.2 +------------------- + + * The "parse_config_key()" API function has been cleaned up. + + * An helper function to make it easier to append the result from + real_path() to a strbuf has been added. + + * The t/perf performance test suite was not prepared to test not so + old versions of Git, but now it covers versions of Git that are not + so ancient. + + * Picking two versions of Git and running tests to make sure the + older one and the newer one interoperate happily has now become + possible. + + * Teach the "debug" helper used in the test framework that allows a + command to run under "gdb" to make the session interactive. + + * "git repack --depth=" for a long time busted the specified depth + when reusing delta from existing packs. This has been corrected. + + * user.email that consists of only cruft chars should consistently + error out, but didn't. + + * A few tests were run conditionally under (rare) conditions where + they cannot be run (like running cvs tests under 'root' account). + + * "git branch @" created refs/heads/@ as a branch, and in general the + code that handled @{-1} and @{upstream} was a bit too loose in + disambiguating. + + * "git fetch" that requests a commit by object name, when the other + side does not allow such an request, failed without much + explanation. + + * "git filter-branch --prune-empty" drops a single-parent commit that + becomes a no-op, but did not drop a root commit whose tree is empty. + + * Recent versions of Git treats http alternates (used in dumb http + transport) just like HTTP redirects and requires the client to + enable following it, due to security concerns. But we forgot to + give a warning when we decide not to honor the alternates. + + * NO_PTHREADS build has been broken for some time; now fixed. + + * Fix for potential segv introduced in v2.11.0 and later (also + v2.10.2). + + * A few unterminated here documents in tests were fixed, which in + turn revealed incorrect expectations the tests make. These tests + have been updated. + + * "git-shell" rejects a request to serve a repository whose name + begins with a dash, which makes it no longer possible to get it + confused into spawning service programs like "git-upload-pack" with + an option like "--help", which in turn would spawn an interactive + pager, instead of working with the repository user asked to access + (i.e. the one whose name is "--help"). + +Also contains various documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.12.4.txt b/Documentation/RelNotes/2.12.4.txt new file mode 100644 index 00000000000000..3f569382211d49 --- /dev/null +++ b/Documentation/RelNotes/2.12.4.txt @@ -0,0 +1,4 @@ +Git v2.12.4 Release Notes +========================= + +This release forward-ports the fix for "ssh://..." URL from Git v2.7.6 diff --git a/Documentation/RelNotes/2.12.5.txt b/Documentation/RelNotes/2.12.5.txt new file mode 100644 index 00000000000000..8fa73cfce7fa2d --- /dev/null +++ b/Documentation/RelNotes/2.12.5.txt @@ -0,0 +1,17 @@ +Git v2.12.5 Release Notes +========================= + +Fixes since v2.12.4 +------------------- + + * "git cvsserver" no longer is invoked by "git daemon" by default, + as it is old and largely unmaintained. + + * Various Perl scripts did not use safe_pipe_capture() instead of + backticks, leaving them susceptible to end-user input. They have + been corrected. + +Credits go to joernchen for finding the +unsafe constructs in "git cvsserver", and to Jeff King at GitHub for +finding and fixing instances of the same issue in other scripts. + diff --git a/Documentation/RelNotes/2.13.0.txt b/Documentation/RelNotes/2.13.0.txt new file mode 100644 index 00000000000000..2a47b4cb0cd4c7 --- /dev/null +++ b/Documentation/RelNotes/2.13.0.txt @@ -0,0 +1,618 @@ +Git 2.13 Release Notes +====================== + +Backward compatibility notes. + + * Use of an empty string as a pathspec element that is used for + 'everything matches' is still warned and Git asks users to use a + more explicit '.' for that instead. The hope is that existing + users will not mind this change, and eventually the warning can be + turned into a hard error, upgrading the deprecation into removal of + this (mis)feature. That is not scheduled to happen in the upcoming + release (yet). + + * The historical argument order "git merge HEAD ..." + has been deprecated for quite some time, and is now removed. + + * The default location "~/.git-credential-cache/socket" for the + socket used to communicate with the credential-cache daemon has + been moved to "~/.cache/git/credential/socket". + + * Git now avoids blindly falling back to ".git" when the setup + sequence said we are _not_ in Git repository. A corner case that + happens to work right now may be broken by a call to die("BUG"). + We've tried hard to locate such cases and fixed them, but there + might still be cases that need to be addressed--bug reports are + greatly appreciated. + + +Updates since v2.12 +------------------- + +UI, Workflows & Features + + * "git describe" and "git name-rev" have been taught to take more + than one refname patterns to restrict the set of refs to base their + naming output on, and also learned to take negative patterns to + name refs not to be used for naming via their "--exclude" option. + + * Deletion of a branch "foo/bar" could remove .git/refs/heads/foo + once there no longer is any other branch whose name begins with + "foo/", but we didn't do so so far. Now we do. + + * When "git merge" detects a path that is renamed in one history + while the other history deleted (or modified) it, it now reports + both paths to help the user understand what is going on in the two + histories being merged. + + * The part in "http.." configuration variable + can now be spelled with '*' that serves as wildcard. + E.g. "http.https://*.example.com.proxy" can be used to specify the + proxy used for https://a.example.com, https://b.example.com, etc., + i.e. any host in the example.com domain. + + * "git tag" did not leave useful message when adding a new entry to + reflog; this was left unnoticed for a long time because refs/tags/* + doesn't keep reflog by default. + + * The "negative" pathspec feature was somewhat more cumbersome to use + than necessary in that its short-hand used "!" which needed to be + escaped from shells, and it required "exclude from what?" specified. + + * The command line options for ssh invocation needs to be tweaked for + some implementations of SSH (e.g. PuTTY plink wants "-P " + while OpenSSH wants "-p " to specify port to connect to), and + the variant was guessed when GIT_SSH environment variable is used + to specify it. The logic to guess now applies to the command + specified by the newer GIT_SSH_COMMAND and also core.sshcommand + configuration variable, and comes with an escape hatch for users to + deal with misdetected cases. + + * The "--git-path", "--git-common-dir", and "--shared-index-path" + options of "git rev-parse" did not produce usable output. They are + now updated to show the path to the correct file, relative to where + the caller is. + + * "git diff -W" has been taught to handle the case where a new + function is added at the end of the file better. + + * "git update-ref -d" and other operations to delete references did + not leave any entry in HEAD's reflog when the reference being + deleted was the current branch. This is not a problem in practice + because you do not want to delete the branch you are currently on, + but caused renaming of the current branch to something else not to + be logged in a useful way. + + * "Cc:" on the trailer part does not have to conform to RFC strictly, + unlike in the e-mail header. "git send-email" has been updated to + ignore anything after '>' when picking addresses, to allow non-address + cruft like " # stable 4.4" after the address. + + * When "git submodule init" decides that the submodule in the working + tree is its upstream, it now gives a warning as it is not a very + common setup. + + * "git stash push" takes a pathspec so that the local changes can be + stashed away only partially. + + * Documentation for "git ls-files" did not refer to core.quotePath. + + * The experimental "split index" feature has gained a few + configuration variables to make it easier to use. + + * From a working tree of a repository, a new option of "rev-parse" + lets you ask if the repository is used as a submodule of another + project, and where the root level of the working tree of that + project (i.e. your superproject) is. + + * The pathspec mechanism learned to further limit the paths that + match the pattern to those that have specified attributes attached + via the gitattributes mechanism. + + * Our source code has used the SHA1_HEADER cpp macro after "#include" + in the C code to switch among the SHA-1 implementations. Instead, + list the exact header file names and switch among implementations + using "#ifdef BLK_SHA1/#include "block-sha1/sha1.h"/.../#endif"; + this helps some IDE tools. + + * The start-up sequence of "git" needs to figure out some configured + settings before it finds and set itself up in the location of the + repository and was quite messy due to its "chicken-and-egg" nature. + The code has been restructured. + + * The command line prompt (in contrib/) learned a new 'tag' style + that can be specified with GIT_PS1_DESCRIBE_STYLE, to describe a + detached HEAD with "git describe --tags". + + * The configuration file learned a new "includeIf..path" + that includes the contents of the given path only when the + condition holds. This allows you to say "include this work-related + bit only in the repositories under my ~/work/ directory". + + * Recent update to "rebase -i" started showing a message that is not + a warning with "warning:" prefix by mistake. This has been fixed. + + * Recently we started passing the "--push-options" through the + external remote helper interface; now the "smart HTTP" remote + helper understands what to do with the passed information. + + * "git describe --dirty" dies when it cannot be determined if the + state in the working tree matches that of HEAD (e.g. broken + repository or broken submodule). The command learned a new option + "git describe --broken" to give "$name-broken" (where $name is the + description of HEAD) in such a case. + + * "git checkout" is taught the "--recurse-submodules" option. + + * Recent enhancement to "git stash push" command to support pathspec + to allow only a subset of working tree changes to be stashed away + was found to be too chatty and exposed the internal implementation + detail (e.g. when it uses reset to match the index to HEAD before + doing other things, output from reset seeped out). These, and + other chattyness has been fixed. + + * "git merge HEAD " syntax that has been deprecated + since October 2007 has been removed. + + * The refs completion for large number of refs has been sped up, + partly by giving up disambiguating ambiguous refs and partly by + eliminating most of the shell processing between 'git for-each-ref' + and 'ls-remote' and Bash's completion facility. + + * On many keyboards, typing "@{" involves holding down SHIFT key and + one can easily end up with "@{Up..." when typing "@{upstream}". As + the upstream/push keywords do not appear anywhere else in the syntax, + we can safely accept them case insensitively without introducing + ambiguity or confusion to solve this. + + * "git tag/branch/for-each-ref" family of commands long allowed to + filter the refs by "--contains X" (show only the refs that are + descendants of X), "--merged X" (show only the refs that are + ancestors of X), "--no-merged X" (show only the refs that are not + ancestors of X). One curious omission, "--no-contains X" (show + only the refs that are not descendants of X) has been added to + them. + + * The default behaviour of "git log" in an interactive session has + been changed to enable "--decorate". + + * The output from "git status --short" has been extended to show + various kinds of dirtiness in submodules differently; instead of to + "M" for modified, 'm' and '?' can be shown to signal changes only + to the working tree of the submodule but not the commit that is + checked out. + + * Allow the http.postbuffer configuration variable to be set to a + size that can be expressed in size_t, which can be larger than + ulong on some platforms. + + * "git rebase" learns "--signoff" option. + + * The completion script (in contrib/) learned to complete "git push + --delete b" to complete branch name to be deleted. + + * "git worktree add --lock" allows to lock a worktree immediately + after it's created. This helps prevent a race between "git worktree + add; git worktree lock" and "git worktree prune". + + * Completion for "git checkout " that auto-creates the branch + out of a remote tracking branch can now be disabled, as this + completion often gets in the way when completing to checkout an + existing local branch that happens to share the same prefix with + bunch of remote tracking branches. + + +Performance, Internal Implementation, Development Support etc. + + * The code to list branches in "git branch" has been consolidated + with the more generic ref-filter API. + + * Resource usage while enumerating refs from alternate object store + has been optimized to help receiving end of "push" that hosts a + repository with many "forks". + + * The gitattributes machinery is being taught to work better in a + multi-threaded environment. + + * "git rebase -i" starts using the recently updated "sequencer" code. + + * Code and design clean-up for the refs API. + + * The preload-index code has been taught not to bother with the index + entries that are paths that are not checked out by "sparse checkout". + + * Some warning() messages from "git clean" were updated to show the + errno from failed system calls. + + * The "parse_config_key()" API function has been cleaned up. + + * A test that creates a confusing branch whose name is HEAD has been + corrected not to do so. + + * The code that parses header fields in the commit object has been + updated for (micro)performance and code hygiene. + + * An helper function to make it easier to append the result from + real_path() to a strbuf has been added. + + * Reduce authentication round-trip over HTTP when the server supports + just a single authentication method. This also improves the + behaviour when Git is misconfigured to enable http.emptyAuth + against a server that does not authenticate without a username + (i.e. not using Kerberos etc., which makes http.emptyAuth + pointless). + + * Windows port wants to use OpenSSL's implementation of SHA-1 + routines, so let them. + + * The t/perf performance test suite was not prepared to test not so + old versions of Git, but now it covers versions of Git that are not + so ancient. + + * Add 32-bit Linux variant to the set of platforms to be tested with + Travis CI. + + * "git branch --list" takes the "--abbrev" and "--no-abbrev" options + to control the output of the object name in its "-v"(erbose) + output, but a recent update started ignoring them; fix it before + the breakage reaches to any released version. + + * Picking two versions of Git and running tests to make sure the + older one and the newer one interoperate happily has now become + possible. + + * "git tag --contains" used to (ab)use the object bits to keep track + of the state of object reachability without clearing them after + use; this has been cleaned up and made to use the newer commit-slab + facility. + + * The "debug" helper used in the test framework learned to run + a command under "gdb" interactively. + + * The "detect attempt to create collisions" variant of SHA-1 + implementation by Marc Stevens (CWI) and Dan Shumow (Microsoft) + has been integrated and made the default. + + * The test framework learned to detect unterminated here documents. + + * The name-hash used for detecting paths that are different only in + cases (which matter on case insensitive filesystems) has been + optimized to take advantage of multi-threading when it makes sense. + + * An earlier version of sha1dc/sha1.c that was merged to 'master' + compiled incorrectly on Windows, which has been fixed. + + * "what URL do we want to update this submodule?" and "are we + interested in this submodule?" are split into two distinct + concepts, and then the way used to express the latter got extended, + paving a way to make it easier to manage a project with many + submodules and make it possible to later extend use of multiple + worktrees for a project with submodules. + + * Some debugging output from "git describe" were marked for l10n, + but some weren't. Mark missing ones for l10n. + + * Define a new task in .travis.yml that triggers a test session on + Windows run elsewhere. + + * Conversion from uchar[20] to struct object_id continues. + + * The "submodule" specific field in the ref_store structure is + replaced with a more generic "gitdir" that can later be used also + when dealing with ref_store that represents the set of refs visible + from the other worktrees. + + * The string-list API used a custom reallocation strategy that was + very inefficient, instead of using the usual ALLOC_GROW() macro, + which has been fixed. + (merge 950a234cbd jh/string-list-micro-optim later to maint). + + * In a 2- and 3-way merge of trees, more than one source trees often + end up sharing an identical subtree; optimize by not reading the + same tree multiple times in such a case. + (merge d12a8cf0af jh/unpack-trees-micro-optim later to maint). + + * The index file has a trailing SHA-1 checksum to detect file + corruption, and historically we checked it every time the index + file is used. Omit the validation during normal use, and instead + verify only in "git fsck". + + * Having a git command on the upstream side of a pipe in a test + script will hide the exit status from the command, which may cause + us to fail to notice a breakage; rewrite tests in a script to avoid + this issue. + + * Travis CI learns to run coccicheck. + + * "git checkout" that handles a lot of paths has been optimized by + reducing the number of unnecessary checks of paths in the + has_dir_name() function. + + * The internals of the refs API around the cached refs has been + streamlined. + + * Output from perf tests have been updated to align their titles. + +Also contains various documentation updates and code clean-ups. + + +Fixes since v2.12 +----------------- + +Unless otherwise noted, all the fixes since v2.12 in the maintenance +track are contained in this release (see the maintenance releases' +notes for details). + + * "git repack --depth=" for a long time busted the specified depth + when reusing delta from existing packs. This has been corrected. + + * The code to parse the command line "git grep ... + [[--] ...]" has been cleaned up, and a handful of bugs + have been fixed (e.g. we used to check "--" if it is a rev). + + * "git ls-remote" and "git archive --remote" are designed to work + without being in a directory under Git's control. However, recent + updates revealed that we randomly look into a directory called + .git/ without actually doing necessary set-up when working in a + repository. Stop doing so. + + * "git show-branch" expected there were only very short branch names + in the repository and used a fixed-length buffer to hold them + without checking for overflow. + + * A caller of tempfile API that uses stdio interface to write to + files may ignore errors while writing, which is detected when + tempfile is closed (with a call to ferror()). By that time, the + original errno that may have told us what went wrong is likely to + be long gone and was overwritten by an irrelevant value. + close_tempfile() now resets errno to EIO to make errno at least + predictable. + + * "git remote rm X", when a branch has remote X configured as the + value of its branch.*.remote, tried to remove branch.*.remote and + branch.*.merge and failed if either is unset. + + * A "gc.log" file left by a backgrounded "gc --auto" disables further + automatic gc; it has been taught to run at least once a day (by + default) by ignoring a stale "gc.log" file that is too old. + + * The code to parse "git -c VAR=VAL cmd" and set configuration + variable for the duration of cmd had two small bugs, which have + been fixed. + + * user.email that consists of only cruft chars should consistently + error out, but didn't. + + * "git upload-pack", which is a counter-part of "git fetch", did not + report a request for a ref that was not advertised as invalid. + This is generally not a problem (because "git fetch" will stop + before making such a request), but is the right thing to do. + + * A leak in a codepath to read from a packed object in (rare) cases + has been plugged. + + * When a redirected http transport gets an error during the + redirected request, we ignored the error we got from the server, + and ended up giving a not-so-useful error message. + + * The patch subcommand of "git add -i" was meant to have paths + selection prompt just like other subcommand, unlike "git add -p" + directly jumps to hunk selection. Recently, this was broken and + "add -i" lost the paths selection dialog, but it now has been + fixed. + + * Git v2.12 was shipped with an embarrassing breakage where various + operations that verify paths given from the user stopped dying when + seeing an issue, and instead later triggering segfault. + + * There is no need for Python only to give a few messages to the + standard error stream, but we somehow did. + + * The code to parse "git log -L..." command line was buggy when there + are many ranges specified with -L; overrun of the allocated buffer + has been fixed. + + * The command-line parsing of "git log -L" copied internal data + structures using incorrect size on ILP32 systems. + + * "git diff --quiet" relies on the size field in diff_filespec to be + correctly populated, but diff_populate_filespec() helper function + made an incorrect short-cut when asked only to populate the size + field for paths that need to go through convert_to_git() (e.g. CRLF + conversion). + + * A few tests were run conditionally under (rare) conditions where + they cannot be run (like running cvs tests under 'root' account). + + * "git branch @" created refs/heads/@ as a branch, and in general the + code that handled @{-1} and @{upstream} was a bit too loose in + disambiguating. + + * "git fetch" that requests a commit by object name, when the other + side does not allow such an request, failed without much + explanation. + + * "git filter-branch --prune-empty" drops a single-parent commit that + becomes a no-op, but did not drop a root commit whose tree is empty. + + * Recent versions of Git treats http alternates (used in dumb http + transport) just like HTTP redirects and requires the client to + enable following it, due to security concerns. But we forgot to + give a warning when we decide not to honor the alternates. + + * "git push" had a handful of codepaths that could lead to a deadlock + when unexpected error happened, which has been fixed. + + * "Dumb http" transport used to misparse a nonsense http-alternates + response, which has been fixed. + + * "git add -p " unnecessarily expanded the pathspec to a + list of individual files that matches the pathspec by running "git + ls-files ", before feeding it to "git diff-index" to see + which paths have changes, because historically the pathspec + language supported by "diff-index" was weaker. These days they are + equivalent and there is no reason to internally expand it. This + helps both performance and avoids command line argument limit on + some platforms. + (merge 7288e12cce jk/add-i-use-pathspecs later to maint). + + * "git status --porcelain" is supposed to give a stable output, but a + few strings were left as translatable by mistake. + + * "git revert -m 0 $merge_commit" complained that reverting a merge + needs to say relative to which parent the reversion needs to + happen, as if "-m 0" weren't given. The correct diagnosis is that + "-m 0" does not refer to the first parent ("-m 1" does). This has + been fixed. + + * Code to read submodule..ignore config did not state the + variable name correctly when giving an error message diagnosing + misconfiguration. + + * Fix for NO_PTHREADS build. + + * Fix for potential segv introduced in v2.11.0 and later (also + v2.10.2) to "git log --pickaxe-regex -S". + + * A few unterminated here documents in tests were fixed, which in + turn revealed incorrect expectations the tests make. These tests + have been updated. + + * Fix for NO_PTHREADS option. + (merge 2225e1ea20 bw/grep-recurse-submodules later to maint). + + * Git now avoids blindly falling back to ".git" when the setup + sequence said we are _not_ in Git repository. A corner case that + happens to work right now may be broken by a call to die("BUG"). + (merge b1ef400eec jk/no-looking-at-dotgit-outside-repo-final later to maint). + + * A few commands that recently learned the "--recurse-submodule" + option misbehaved when started from a subdirectory of the + superproject. + (merge b2dfeb7c00 bw/recurse-submodules-relative-fix later to maint). + + * FreeBSD implementation of getcwd(3) behaved differently when an + intermediate directory is unreadable/unsearchable depending on the + length of the buffer provided, which our strbuf_getcwd() was not + aware of. strbuf_getcwd() has been taught to cope with it better. + (merge a54e938e5b rs/freebsd-getcwd-workaround later to maint). + + * A recent update to "rebase -i" stopped running hooks for the "git + commit" command during "reword" action, which has been fixed. + + * Removing an entry from a notes tree and then looking another note + entry from the resulting tree using the internal notes API + functions did not work as expected. No in-tree users of the API + has such access pattern, but it still is worth fixing. + + * "git receive-pack" could have been forced to die by attempting + allocate an unreasonably large amount of memory with a crafted push + certificate; this has been fixed. + (merge f2214dede9 bc/push-cert-receive-fix later to maint). + + * Update error handling for codepath that deals with corrupt loose + objects. + (merge 51054177b3 jk/loose-object-info-report-error later to maint). + + * "git diff --submodule=diff" learned to work better in a project + with a submodule that in turn has its own submodules. + (merge 17b254cda6 sb/show-diff-for-submodule-in-diff-fix later to maint). + + * Update the build dependency so that an update to /usr/bin/perl + etc. result in recomputation of perl.mak file. + (merge c59c4939c2 ab/regen-perl-mak-with-different-perl later to maint). + + * "git push --recurse-submodules --push-option=" learned to + propagate the push option recursively down to pushes in submodules. + + * If a patch e-mail had its first paragraph after an in-body header + indented (even after a blank line after the in-body header line), + the indented line was mistook as a continuation of the in-body + header. This has been fixed. + (merge fd1062e52e lt/mailinfo-in-body-header-continuation later to maint). + + * Clean up fallouts from recent tightening of the set-up sequence, + where Git barfs when repository information is accessed without + first ensuring that it was started in a repository. + (merge bccb22cbb1 jk/no-looking-at-dotgit-outside-repo later to maint). + + * "git p4" used "name-rev HEAD" when it wants to learn what branch is + checked out; it should use "symbolic-ref HEAD". + (merge eff451101d ld/p4-current-branch-fix later to maint). + + * "http.proxy" set to an empty string is used to disable the usage of + proxy. We broke this early last year. + (merge ae51d91105 sr/http-proxy-configuration-fix later to maint). + + * $GIT_DIR may in some cases be normalized with all symlinks resolved + while "gitdir" path expansion in the pattern does not receive the + same treatment, leading to incorrect mismatch. This has been fixed. + + * "git submodule" script does not work well with strange pathnames. + Protect it from a path with slashes in them, at least. + + * "git fetch-pack" was not prepared to accept ERR packet that the + upload-pack can send with a human-readable error message. It + showed the packet contents with ERR prefix, so there was no data + loss, but it was redundant to say "ERR" in an error message. + (merge 8e2c7bef03 jt/fetch-pack-error-reporting later to maint). + + * "ls-files --recurse-submodules" did not quite work well in a + project with nested submodules. + + * gethostname(2) may not NUL terminate the buffer if hostname does + not fit; unfortunately there is no easy way to see if our buffer + was too small, but at least this will make sure we will not end up + using garbage past the end of the buffer. + (merge 5781a9a270 dt/xgethostname-nul-termination later to maint). + + * A recent update broke "git add -p ../foo" from a subdirectory. + + * While handy, "git_path()" is a dangerous function to use as a + callsite that uses it safely one day can be broken by changes + to other code that calls it. Reduction of its use continues. + (merge 16d2676c9e jk/war-on-git-path later to maint). + + * The split-index code configuration code used an unsafe git_path() + function without copying its result out. + + * Many stale HTTP(s) links have been updated in our documentation. + (merge 613416f0be jk/update-links-in-docs later to maint). + + * "git-shell" rejects a request to serve a repository whose name + begins with a dash, which makes it no longer possible to get it + confused into spawning service programs like "git-upload-pack" with + an option like "--help", which in turn would spawn an interactive + pager, instead of working with the repository user asked to access + (i.e. the one whose name is "--help"). + + * Other minor doc, test and build updates and code cleanups. + (merge df2a6e38b7 jk/pager-in-use later to maint). + (merge 75ec4a6cb0 ab/branch-list-doc later to maint). + (merge 3e5b36c637 sg/skip-prefix-in-prettify-refname later to maint). + (merge 2c5e2865cc jk/fast-import-cleanup later to maint). + (merge 4473060bc2 ab/test-readme-updates later to maint). + (merge 48a96972fd ab/doc-submitting later to maint). + (merge f5c2bc2b96 jk/make-coccicheck-detect-errors later to maint). + (merge c105f563d1 cc/untracked later to maint). + (merge 8668976b53 jc/unused-symbols later to maint). + (merge fba275dc93 jc/bs-t-is-not-a-tab-for-sed later to maint). + (merge be6ed145de mm/ls-files-s-doc later to maint). + (merge 60b091c679 qp/bisect-docfix later to maint). + (merge 47242cd103 ah/diff-files-ours-theirs-doc later to maint). + (merge 35ad44cbd8 sb/submodule-rm-absorb later to maint). + (merge 0301f1fd92 va/i18n-perl-scripts later to maint). + (merge 733e064d98 vn/revision-shorthand-for-side-branch-log later to maint). + (merge 85999743e7 tb/doc-eol-normalization later to maint). + (merge 0747fb49fd jk/loose-object-fsck later to maint). + (merge d8f4481c4f jk/quarantine-received-objects later to maint). + (merge 7ba1ceef95 xy/format-patch-base later to maint). + (merge fa1912c89a rs/misc-cppcheck-fixes later to maint). + (merge f17d642d3b ab/push-cas-doc-n-test later to maint). + (merge 61e282425a ss/gitmodules-ignore-doc later to maint). + (merge 8d3047cd5b ss/submodule-shallow-doc later to maint). + (merge 1f9e18b772 jk/prio-queue-avoid-swap-with-self later to maint). + (merge 627fde1025 jk/submodule-init-segv-fix later to maint). + (merge d395745d81 rg/doc-pull-typofix later to maint). + (merge 01e60a9a22 rg/doc-submittingpatches-wordfix later to maint). + (merge 501d3cd7b8 sr/hooks-cwd-doc later to maint). diff --git a/Documentation/RelNotes/2.13.1.txt b/Documentation/RelNotes/2.13.1.txt new file mode 100644 index 00000000000000..ed7cd976d92324 --- /dev/null +++ b/Documentation/RelNotes/2.13.1.txt @@ -0,0 +1,114 @@ +Git v2.13.1 Release Notes +========================= + +Fixes since v2.13 +----------------- + + * The Web interface to gmane news archive is long gone, even though + the articles are still accessible via NTTP. Replace the links with + ones to public-inbox.org. Because their message identification is + based on the actual message-id, it is likely that it will be easier + to migrate away from it if/when necessary. + + * Update tests to pass under GETTEXT_POISON (a mechanism to ensure + that output strings that should not be translated are not + translated by mistake), and tell TravisCI to run them. + + * Setting "log.decorate=false" in the configuration file did not take + effect in v2.13, which has been corrected. + + * An earlier update to test 7400 needed to be skipped on CYGWIN. + + * Git sometimes gives an advice in a rhetorical question that does + not require an answer, which can confuse new users and non native + speakers. Attempt to rephrase them. + + * "git read-tree -m" (no tree-ish) gave a nonsense suggestion "use + --empty if you want to clear the index". With "-m", such a request + will still fail anyway, as you'd need to name at least one tree-ish + to be merged. + + * The codepath in "git am" that is used when running "git rebase" + leaked memory held for the log message of the commits being rebased. + + * "pack-objects" can stream a slice of an existing packfile out when + the pack bitmap can tell that the reachable objects are all needed + in the output, without inspecting individual objects. This + strategy however would not work well when "--local" and other + options are in use, and need to be disabled. + + * Clarify documentation for include.path and includeIf..path + configuration variables. + + * Tag objects, which are not reachable from any ref, that point at + missing objects were mishandled by "git gc" and friends (they + should silently be ignored instead) + + * A few http:// links that are redirected to https:// in the + documentation have been updated to https:// links. + + * Make sure our tests would pass when the sources are checked out + with "platform native" line ending convention by default on + Windows. Some "text" files out tests use and the test scripts + themselves that are meant to be run with /bin/sh, ought to be + checked out with eol=LF even on Windows. + + * Fix memory leaks pointed out by Coverity (and people). + + * The receive-pack program now makes sure that the push certificate + records the same set of push options used for pushing. + + * "git cherry-pick" and other uses of the sequencer machinery + mishandled a trailer block whose last line is an incomplete line. + This has been fixed so that an additional sign-off etc. are added + after completing the existing incomplete line. + + * The shell completion script (in contrib/) learned "git stash" has + a new "push" subcommand. + + * Travis CI gained a task to format the documentation with both + AsciiDoc and AsciiDoctor. + + * Update the C style recommendation for notes for translators, as + recent versions of gettext tools can work with our style of + multi-line comments. + + * "git clone --config var=val" is a way to populate the + per-repository configuration file of the new repository, but it did + not work well when val is an empty string. This has been fixed. + + * A few codepaths in "checkout" and "am" working on an unborn branch + tried to access an uninitialized piece of memory. + + * "git for-each-ref --format=..." with %(HEAD) in the format used to + resolve the HEAD symref as many times as it had processed refs, + which was wasteful, and "git branch" shared the same problem. + + * "git interpret-trailers", when used as GIT_EDITOR for "git commit + -v", looked for and appended to a trailer block at the very end, + i.e. at the end of the "diff" output. The command has been + corrected to pay attention to the cut-mark line "commit -v" adds to + the buffer---the real trailer block should appear just before it. + + * A test allowed both "git push" and "git receive-pack" on the other + end write their traces into the same file. This is OK on platforms + that allows atomically appending to a file opened with O_APPEND, + but on other platforms led to a mangled output, causing + intermittent test failures. This has been fixed by disabling + traces from "receive-pack" in the test. + + * "foo\bar\baz" in "git fetch foo\bar\baz", even though there is no + slashes in it, cannot be a nickname for a remote on Windows, as + that is likely to be a pathname on a local filesystem. + + * The "collision detecting" SHA-1 implementation shipped with 2.13 + was quite broken on some big-endian platforms and/or platforms that + do not like unaligned fetches. Update to the upstream code which + has already fixed these issues. + + * "git am -h" triggered a BUG(). + + * The interaction of "url.*.insteadOf" and custom URL scheme's + whitelisting is now documented better. + +Also contains various documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.13.2.txt b/Documentation/RelNotes/2.13.2.txt new file mode 100644 index 00000000000000..8c2b20071ed2bb --- /dev/null +++ b/Documentation/RelNotes/2.13.2.txt @@ -0,0 +1,54 @@ +Git v2.13.2 Release Notes +========================= + +Fixes since v2.13.1 +------------------- + + * The "collision detecting" SHA-1 implementation shipped with 2.13.1 + was still broken on some platforms. Update to the upstream code + again to take their fix. + + * "git checkout --recurse-submodules" did not quite work with a + submodule that itself has submodules. + + * Introduce the BUG() macro to improve die("BUG: ..."). + + * The "run-command" API implementation has been made more robust + against dead-locking in a threaded environment. + + * A recent update to t5545-push-options.sh started skipping all the + tests in the script when a web server testing is disabled or + unavailable, not just the ones that require a web server. Non HTTP + tests have been salvaged to always run in this script. + + * "git clean -d" used to clean directories that has ignored files, + even though the command should not lose ignored ones without "-x". + "git status --ignored" did not list ignored and untracked files + without "-uall". These have been corrected. + + * The timestamp of the index file is now taken after the file is + closed, to help Windows, on which a stale timestamp is reported by + fstat() on a file that is opened for writing and data was written + but not yet closed. + + * "git pull --rebase --autostash" didn't auto-stash when the local history + fast-forwards to the upstream. + + * "git describe --contains" penalized light-weight tags so much that + they were almost never considered. Instead, give them about the + same chance to be considered as an annotated tag that is the same + age as the underlying commit would. + + * The result from "git diff" that compares two blobs, e.g. "git diff + $commit1:$path $commit2:$path", used to be shown with the full + object name as given on the command line, but it is more natural to + use the $path in the output and use it to look up .gitattributes. + + * A flaky test has been corrected. + + * Help contributors that visit us at GitHub. + + * "git stash push " did not work from a subdirectory at all. + Bugfix for a topic in v2.13 + +Also contains various documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.13.3.txt b/Documentation/RelNotes/2.13.3.txt new file mode 100644 index 00000000000000..384e4de2652636 --- /dev/null +++ b/Documentation/RelNotes/2.13.3.txt @@ -0,0 +1,62 @@ +Git v2.13.3 Release Notes +========================= + +Fixes since v2.13.2 +------------------- + + * The "collision detecting" SHA-1 implementation shipped with 2.13.2 + was still broken on some platforms. Update to the upstream code + again to take their fix. + + * The 'diff-highlight' program (in contrib/) has been restructured + for easier reuse by an external project 'diff-so-fancy'. + + * "git mergetool" learned to work around a wrapper MacOS X adds + around underlying meld. + + * An example in documentation that does not work in multi worktree + configuration has been corrected. + + * The pretty-format specifiers like '%h', '%t', etc. had an + optimization that no longer works correctly. In preparation/hope + of getting it correctly implemented, first discard the optimization + that is broken. + + * The code to pick up and execute command alias definition from the + configuration used to switch to the top of the working tree and + then come back when the expanded alias was executed, which was + unnecessarily complex. Attempt to simplify the logic by using the + early-config mechanism that does not chdir around. + + * "git add -p" were updated in 2.12 timeframe to cope with custom + core.commentchar but the implementation was buggy and a + metacharacter like $ and * did not work. + + * Fix a recent regression to "git rebase -i" and add tests that would + have caught it and others. + + * An unaligned 32-bit access in pack-bitmap code has been corrected. + + * Tighten error checks for invalid "git apply" input. + + * The split index code did not honor core.sharedrepository setting + correctly. + + * The Makefile rule in contrib/subtree for building documentation + learned to honour USE_ASCIIDOCTOR just like the main documentation + set does. + + * A few tests that tried to verify the contents of push certificates + did not use 'git rev-parse' to formulate the line to look for in + the certificate correctly. + + * After "git branch --move" of the currently checked out branch, the + code to walk the reflog of HEAD via "log -g" and friends + incorrectly stopped at the reflog entry that records the renaming + of the branch. + + * The rewrite of "git branch --list" using for-each-ref's internals + that happened in v2.13 regressed its handling of color.branch.local; + this has been fixed. + +Also contains various documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.13.4.txt b/Documentation/RelNotes/2.13.4.txt new file mode 100644 index 00000000000000..9a9f8f9599df8f --- /dev/null +++ b/Documentation/RelNotes/2.13.4.txt @@ -0,0 +1,28 @@ +Git v2.13.4 Release Notes +========================= + +Fixes since v2.13.3 +------------------- + + * Update the character width tables. + + * A recent update broke an alias that contained an uppercase letter, + which has been fixed. + + * On Cygwin, similar to Windows, "git push //server/share/repository" + ought to mean a repository on a network share that can be accessed + locally, but this did not work correctly due to stripping the double + slashes at the beginning. + + * The progress meter did not give a useful output when we haven't had + 0.5 seconds to measure the throughput during the interval. Instead + show the overall throughput rate at the end, which is a much more + useful number. + + * We run an early part of "git gc" that deals with refs before + daemonising (and not under lock) even when running a background + auto-gc, which caused multiple gc processes attempting to run the + early part at the same time. This is now prevented by running the + early part also under the GC lock. + +Also contains a handful of small code and documentation clean-ups. diff --git a/Documentation/RelNotes/2.13.5.txt b/Documentation/RelNotes/2.13.5.txt new file mode 100644 index 00000000000000..6949fcda78df70 --- /dev/null +++ b/Documentation/RelNotes/2.13.5.txt @@ -0,0 +1,4 @@ +Git v2.13.5 Release Notes +========================= + +This release forward-ports the fix for "ssh://..." URL from Git v2.7.6 diff --git a/Documentation/RelNotes/2.13.6.txt b/Documentation/RelNotes/2.13.6.txt new file mode 100644 index 00000000000000..afcae9c808de27 --- /dev/null +++ b/Documentation/RelNotes/2.13.6.txt @@ -0,0 +1,17 @@ +Git v2.13.6 Release Notes +========================= + +Fixes since v2.13.5 +------------------- + + * "git cvsserver" no longer is invoked by "git daemon" by default, + as it is old and largely unmaintained. + + * Various Perl scripts did not use safe_pipe_capture() instead of + backticks, leaving them susceptible to end-user input. They have + been corrected. + +Credits go to joernchen for finding the +unsafe constructs in "git cvsserver", and to Jeff King at GitHub for +finding and fixing instances of the same issue in other scripts. + diff --git a/Documentation/RelNotes/2.13.7.txt b/Documentation/RelNotes/2.13.7.txt new file mode 100644 index 00000000000000..09fc01406c7c7d --- /dev/null +++ b/Documentation/RelNotes/2.13.7.txt @@ -0,0 +1,20 @@ +Git v2.13.7 Release Notes +========================= + +Fixes since v2.13.6 +------------------- + + * Submodule "names" come from the untrusted .gitmodules file, but we + blindly append them to $GIT_DIR/modules to create our on-disk repo + paths. This means you can do bad things by putting "../" into the + name. We now enforce some rules for submodule names which will cause + Git to ignore these malicious names (CVE-2018-11235). + + Credit for finding this vulnerability and the proof of concept from + which the test script was adapted goes to Etienne Stalmans. + + * It was possible to trick the code that sanity-checks paths on NTFS + into reading random piece of memory (CVE-2018-11233). + +Credit for fixing for these bugs goes to Jeff King, Johannes +Schindelin and others. diff --git a/Documentation/RelNotes/2.14.0.txt b/Documentation/RelNotes/2.14.0.txt new file mode 100644 index 00000000000000..2711a2529dadbb --- /dev/null +++ b/Documentation/RelNotes/2.14.0.txt @@ -0,0 +1,517 @@ +Git 2.14 Release Notes +====================== + +Backward compatibility notes and other notable changes. + + * Use of an empty string as a pathspec element that is used for + 'everything matches' is still warned and Git asks users to use a + more explicit '.' for that instead. The hope is that existing + users will not mind this change, and eventually the warning can be + turned into a hard error, upgrading the deprecation into removal of + this (mis)feature. That is not scheduled to happen in the upcoming + release (yet). + + * Git now avoids blindly falling back to ".git" when the setup + sequence said we are _not_ in Git repository. A corner case that + happens to work right now may be broken by a call to die("BUG"). + We've tried hard to locate such cases and fixed them, but there + might still be cases that need to be addressed--bug reports are + greatly appreciated. + + * The experiment to improve the hunk-boundary selection of textual + diff output has finished, and the "indent heuristics" has now + become the default. + + * Git can now be built with PCRE v2 instead of v1 of the PCRE + library. Replace USE_LIBPCRE=YesPlease with USE_LIBPCRE2=YesPlease + in existing build scripts to build against the new version. As the + upstream PCRE maintainer has abandoned v1 maintenance for all but + the most critical bug fixes, use of v2 is recommended. + + +Updates since v2.13 +------------------- + +UI, Workflows & Features + + * The colors in which "git status --short --branch" showed the names + of the current branch and its remote-tracking branch are now + configurable. + + * "git clone" learned the "--no-tags" option not to fetch all tags + initially, and also set up the tagopt not to follow any tags in + subsequent fetches. + + * "git archive --format=zip" learned to use zip64 extension when + necessary to go beyond the 4GB limit. + + * "git reset" learned "--recurse-submodules" option. + + * "git diff --submodule=diff" now recurses into nested submodules. + + * "git repack" learned to accept the --threads= option and pass it + to pack-objects. + + * "git send-email" learned to run sendemail-validate hook to inspect + and reject a message before sending it out. + + * There is no good reason why "git fetch $there $sha1" should fail + when the $sha1 names an object at the tip of an advertised ref, + even when the other side hasn't enabled allowTipSHA1InWant. + + * The "[includeIf "gitdir:$dir"] path=..." mechanism introduced in + 2.13.0 would canonicalize the path of the gitdir being matched, + and did not match e.g. "gitdir:~/work/*" against a repo in + "~/work/main" if "~/work" was a symlink to "/mnt/storage/work". + Now we match both the resolved canonical path and what "pwd" would + show. The include will happen if either one matches. + + * The "indent" heuristics is now the default in "diff". The + diff.indentHeuristic configuration variable can be set to "false" + for those who do not want it. + + * Many commands learned to pay attention to submodule.recurse + configuration. + + * The convention for a command line is to follow "git cmdname + --options" with revisions followed by an optional "--" + disambiguator and then finally pathspecs. When "--" is not there, + we make sure early ones are all interpretable as revs (and do not + look like paths) and later ones are the other way around. A + pathspec with "magic" (e.g. ":/p/a/t/h" that matches p/a/t/h from + the top-level of the working tree, no matter what subdirectory you + are working from) are conservatively judged as "not a path", which + required disambiguation more often. The command line parser + learned to say "it's a pathspec" a bit more often when the syntax + looks like so. + + * Update "perl-compatible regular expression" support to enable JIT + and also allow linking with the newer PCRE v2 library. + + * "filter-branch" learned a pseudo filter "--setup" that can be used + to define common functions/variables that can be used by other + filters. + + * Using "git add d/i/r" when d/i/r is the top of the working tree of + a separate repository would create a gitlink in the index, which + would appear as a not-quite-initialized submodule to others. We + learned to give warnings when this happens. + + * "git status" learned to optionally give how many stash entries there + are in its output. + + * "git status" has long shown essentially the same message as "git + commit"; the message it gives while preparing for the root commit, + i.e. "Initial commit", was hard to understand for some new users. + Now it says "No commits yet" to stress more on the current status + (rather than the commit the user is preparing for, which is more in + line with the focus of "git commit"). + + * "git send-email" now has --batch-size and --relogin-delay options + which can be used to overcome limitations on SMTP servers that + restrict on how many of e-mails can be sent in a single session. + + * An old message shown in the commit log template was removed, as it + has outlived its usefulness. + + * "git pull --rebase --recurse-submodules" learns to rebase the + branch in the submodules to an updated base. + + * "git log" learned -P as a synonym for --perl-regexp, "git grep" + already had such a synonym. + + * "git log" didn't understand --regexp-ignore-case when combined with + --perl-regexp. This has been fixed. + +Performance, Internal Implementation, Development Support etc. + + * The default packed-git limit value has been raised on larger + platforms to save "git fetch" from a (recoverable) failure while + "gc" is running in parallel. + + * Code to update the cache-tree has been tightened so that we won't + accidentally write out any 0{40} entry in the tree object. + + * Attempt to allow us notice "fishy" situation where we fail to + remove the temporary directory used during the test. + + * Travis CI gained a task to format the documentation with both + AsciiDoc and AsciiDoctor. + + * Some platforms have ulong that is smaller than time_t, and our + historical use of ulong for timestamp would mean they cannot + represent some timestamp that the platform allows. Invent a + separate and dedicated timestamp_t (so that we can distinguish + timestamps and a vanilla ulongs, which along is already a good + move), and then declare uintmax_t is the type to be used as the + timestamp_t. + + * We can trigger Windows auto-build tester (credits: Dscho & + Microsoft) from our existing Travis CI tester now. + + * Conversion from uchar[20] to struct object_id continues. + + * Simplify parse_pathspec() codepath and stop it from looking at the + default in-core index. + + * Add perf-test for wildmatch. + + * Code from "conversion using external process" codepath has been + extracted to a separate sub-process.[ch] module. + + * When "git checkout", "git merge", etc. manipulates the in-core + index, various pieces of information in the index extensions are + discarded from the original state, as it is usually not the case + that they are kept up-to-date and in-sync with the operation on the + main index. The untracked cache extension is copied across these + operations now, which would speed up "git status" (as long as the + cache is properly invalidated). + + * The internal implementation of "git grep" has seen some clean-up. + + * Update the C style recommendation for notes for translators, as + recent versions of gettext tools can work with our style of + multi-line comments. + + * The implementation of "ref" API around the "packed refs" have been + cleaned up, in preparation for further changes. + + * The internal logic used in "git blame" has been libified to make it + easier to use by cgit. + + * Our code often opens a path to an optional file, to work on its + contents when we can successfully open it. We can ignore a failure + to open if such an optional file does not exist, but we do want to + report a failure in opening for other reasons (e.g. we got an I/O + error, or the file is there, but we lack the permission to open). + + The exact errors we need to ignore are ENOENT (obviously) and + ENOTDIR (less obvious). Instead of repeating comparison of errno + with these two constants, introduce a helper function to do so. + + * We often try to open a file for reading whose existence is + optional, and silently ignore errors from open/fopen; report such + errors if they are not due to missing files. + + * When an existing repository is used for t/perf testing, we first + create bit-for-bit copy of it, which may grab a transient state of + the repository and freeze it into the repository used for testing, + which then may cause Git operations to fail. Single out "the index + being locked" case and forcibly drop the lock from the copy. + + * Three instances of the same helper function have been consolidated + to one. + + * "fast-import" uses a default pack chain depth that is consistent + with other parts of the system. + + * A new test to show the interaction between the pattern [^a-z] + (which matches '/') and a slash in a path has been added. The + pattern should not match the slash with "pathmatch", but should + with "wildmatch". + + * The 'diff-highlight' program (in contrib/) has been restructured + for easier reuse by an external project 'diff-so-fancy'. + + * A common pattern to free a piece of memory and assign NULL to the + pointer that used to point at it has been replaced with a new + FREE_AND_NULL() macro. + + * Traditionally, the default die() routine had a code to prevent it + from getting called multiple times, which interacted badly when a + threaded program used it (one downside is that the real error may + be hidden and instead the only error message given to the user may + end up being "die recursion detected", which is not very useful). + + * Introduce a "repository" object to eventually make it easier to + work in multiple repositories (the primary focus is to work with + the superproject and its submodules) in a single process. + + * Optimize "what are the object names already taken in an alternate + object database?" query that is used to derive the length of prefix + an object name is uniquely abbreviated to. + + * The hashmap API has been updated so that data to customize the + behaviour of the comparison function can be specified at the time a + hashmap is initialized. + + * The "collision detecting" SHA-1 implementation shipped with 2.13 is + now integrated into git.git as a submodule (the first submodule to + ship with git.git). Clone git.git with --recurse-submodules to get + it. For now a non-submodule copy of the same code is also shipped + as part of the tree. + + * A recent update made it easier to use "-fsanitize=" option while + compiling but supported only one sanitize option. Allow more than + one to be combined, joined with a comma, like "make SANITIZE=foo,bar". + + * Use "p4 -G" to make "p4 changes" output more Python-friendly + to parse. + + * We started using "%" PRItime, imitating "%" PRIuMAX and friends, as + a way to format the internal timestamp value, but this does not + play well with gettext(1) i18n framework, and causes "make pot" + that is run by the l10n coordinator to create a broken po/git.pot + file. This is a possible workaround for that problem. + + * It turns out that Cygwin also needs the fopen() wrapper that + returns failure when a directory is opened for reading. + +Also contains various documentation updates and code clean-ups. + + +Fixes since v2.13 +----------------- + +Unless otherwise noted, all the fixes since v2.13 in the maintenance +track are contained in this release (see the maintenance releases' +notes for details). + + * "git gc" did not interact well with "git worktree"-managed + per-worktree refs. + + * "git cherry-pick" and other uses of the sequencer machinery + mishandled a trailer block whose last line is an incomplete line. + This has been fixed so that an additional sign-off etc. are added + after completing the existing incomplete line. + + * The codepath in "git am" that is used when running "git rebase" + leaked memory held for the log message of the commits being rebased. + + * "git clone --config var=val" is a way to populate the + per-repository configuration file of the new repository, but it did + not work well when val is an empty string. This has been fixed. + + * Setting "log.decorate=false" in the configuration file did not take + effect in v2.13, which has been corrected. + + * A few codepaths in "checkout" and "am" working on an unborn branch + tried to access an uninitialized piece of memory. + + * The Web interface to gmane news archive is long gone, even though + the articles are still accessible via NTTP. Replace the links with + ones to public-inbox.org. Because their message identification is + based on the actual message-id, it is likely that it will be easier + to migrate away from it if/when necessary. + + * The receive-pack program now makes sure that the push certificate + records the same set of push options used for pushing. + + * Tests have been updated to pass under GETTEXT_POISON (a mechanism + to ensure that output strings that should not be translated are + not translated by mistake), and TravisCI is told to run them. + + * "git checkout --recurse-submodules" did not quite work with a + submodule that itself has submodules. + + * "pack-objects" can stream a slice of an existing packfile out when + the pack bitmap can tell that the reachable objects are all needed + in the output, without inspecting individual objects. This + strategy however would not work well when "--local" and other + options are in use, and need to be disabled. + + * Fix memory leaks pointed out by Coverity (and people). + + * "git read-tree -m" (no tree-ish) gave a nonsense suggestion "use + --empty if you want to clear the index". With "-m", such a request + will still fail anyway, as you'd need to name at least one tree-ish + to be merged. + + * Make sure our tests would pass when the sources are checked out + with "platform native" line ending convention by default on + Windows. Some "text" files out tests use and the test scripts + themselves that are meant to be run with /bin/sh, ought to be + checked out with eol=LF even on Windows. + + * Introduce the BUG() macro to improve die("BUG: ..."). + + * Clarify documentation for include.path and includeIf..path + configuration variables. + + * Git sometimes gives an advice in a rhetorical question that does + not require an answer, which can confuse new users and non native + speakers. Attempt to rephrase them. + + * A few http:// links that are redirected to https:// in the + documentation have been updated to https:// links. + + * "git for-each-ref --format=..." with %(HEAD) in the format used to + resolve the HEAD symref as many times as it had processed refs, + which was wasteful, and "git branch" shared the same problem. + + * Regression fix to topic recently merged to 'master'. + + * The shell completion script (in contrib/) learned "git stash" has + a new "push" subcommand. + + * "git interpret-trailers", when used as GIT_EDITOR for "git commit + -v", looked for and appended to a trailer block at the very end, + i.e. at the end of the "diff" output. The command has been + corrected to pay attention to the cut-mark line "commit -v" adds to + the buffer---the real trailer block should appear just before it. + + * A test allowed both "git push" and "git receive-pack" on the other + end write their traces into the same file. This is OK on platforms + that allows atomically appending to a file opened with O_APPEND, + but on other platforms led to a mangled output, causing + intermittent test failures. This has been fixed by disabling + traces from "receive-pack" in the test. + + * Tag objects, which are not reachable from any ref, that point at + missing objects were mishandled by "git gc" and friends (they + should silently be ignored instead) + + * "git describe --contains" penalized light-weight tags so much that + they were almost never considered. Instead, give them about the + same chance to be considered as an annotated tag that is the same + age as the underlying commit would. + + * The "run-command" API implementation has been made more robust + against dead-locking in a threaded environment. + + * A recent update to t5545-push-options.sh started skipping all the + tests in the script when a web server testing is disabled or + unavailable, not just the ones that require a web server. Non HTTP + tests have been salvaged to always run in this script. + + * "git send-email" now uses Net::SMTP::SSL, which is obsolete, only + when needed. Recent versions of Net::SMTP can do TLS natively. + + * "foo\bar\baz" in "git fetch foo\bar\baz", even though there is no + slashes in it, cannot be a nickname for a remote on Windows, as + that is likely to be a pathname on a local filesystem. + + * "git clean -d" used to clean directories that has ignored files, + even though the command should not lose ignored ones without "-x". + "git status --ignored" did not list ignored and untracked files + without "-uall". These have been corrected. + + * The result from "git diff" that compares two blobs, e.g. "git diff + $commit1:$path $commit2:$path", used to be shown with the full + object name as given on the command line, but it is more natural to + use the $path in the output and use it to look up .gitattributes. + + * The "collision detecting" SHA-1 implementation shipped with 2.13 + was quite broken on some big-endian platforms and/or platforms that + do not like unaligned fetches. Update to the upstream code which + has already fixed these issues. + + * "git am -h" triggered a BUG(). + + * The interaction of "url.*.insteadOf" and custom URL scheme's + whitelisting is now documented better. + + * The timestamp of the index file is now taken after the file is + closed, to help Windows, on which a stale timestamp is reported by + fstat() on a file that is opened for writing and data was written + but not yet closed. + + * "git pull --rebase --autostash" didn't auto-stash when the local history + fast-forwards to the upstream. + + * A flaky test has been corrected. + + * "git $cmd -h" for builtin commands calls the implementation of the + command (i.e. cmd_$cmd() function) without doing any repository + set-up, and the commands that expect RUN_SETUP is done by the Git + potty needs to be prepared to show the help text without barfing. + (merge d691551192 jk/consistent-h later to maint). + + * Help contributors that visit us at GitHub. + + * "git stash push " did not work from a subdirectory at all. + Bugfix for a topic in v2.13 + + * As there is no portable way to pass timezone information to + strftime, some output format from "git log" and friends are + impossible to produce. Teach our own strbuf_addftime to replace %z + and %Z with caller-supplied values to help working around this. + (merge 6eced3ec5e rs/strbuf-addftime-zZ later to maint). + + * "git mergetool" learned to work around a wrapper MacOS X adds + around underlying meld. + + * An example in documentation that does not work in multi worktree + configuration has been corrected. + + * The pretty-format specifiers like '%h', '%t', etc. had an + optimization that no longer works correctly. In preparation/hope + of getting it correctly implemented, first discard the optimization + that is broken. + + * The code to pick up and execute command alias definition from the + configuration used to switch to the top of the working tree and + then come back when the expanded alias was executed, which was + unnecessarily complex. Attempt to simplify the logic by using the + early-config mechanism that does not chdir around. + + * Fix configuration codepath to pay proper attention to commondir + that is used in multi-worktree situation, and isolate config API + into its own header file. + (merge dc8441fdb4 bw/config-h later to maint). + + * "git add -p" were updated in 2.12 timeframe to cope with custom + core.commentchar but the implementation was buggy and a + metacharacter like $ and * did not work. + + * A recent regression in "git rebase -i" has been fixed and tests + that would have caught it and others have been added. + + * An unaligned 32-bit access in pack-bitmap code has been corrected. + + * Tighten error checks for invalid "git apply" input. + + * The split index code did not honor core.sharedRepository setting + correctly. + + * The Makefile rule in contrib/subtree for building documentation + learned to honour USE_ASCIIDOCTOR just like the main documentation + set does. + + * Code clean-up to fix possible buffer over-reading. + + * A few tests that tried to verify the contents of push certificates + did not use 'git rev-parse' to formulate the line to look for in + the certificate correctly. + + * Update the character width tables. + + * After "git branch --move" of the currently checked out branch, the + code to walk the reflog of HEAD via "log -g" and friends + incorrectly stopped at the reflog entry that records the renaming + of the branch. + + * The rewrite of "git branch --list" using for-each-ref's internals + that happened in v2.13 regressed its handling of color.branch.local; + this has been fixed. + + * The build procedure has been improved to allow building and testing + Git with address sanitizer more easily. + (merge 425ca6710b jk/build-with-asan later to maint). + + * On Cygwin, similar to Windows, "git push //server/share/repository" + ought to mean a repository on a network share that can be accessed + locally, but this did not work correctly due to stripping the double + slashes at the beginning. + + * The progress meter did not give a useful output when we haven't had + 0.5 seconds to measure the throughput during the interval. Instead + show the overall throughput rate at the end, which is a much more + useful number. + + * Code clean-up, that makes us in sync with Debian by one patch. + + * We run an early part of "git gc" that deals with refs before + daemonising (and not under lock) even when running a background + auto-gc, which caused multiple gc processes attempting to run the + early part at the same time. This is now prevented by running the + early part also under the GC lock. + + * A recent update broke an alias that contained an uppercase letter. + + * Other minor doc, test and build updates and code cleanups. + (merge 5053313562 rs/urlmatch-cleanup later to maint). + (merge 42c78a216e rs/use-div-round-up later to maint). + (merge 5e8d2729ae rs/wt-status-cleanup later to maint). + (merge bc9b7e207f as/diff-options-grammofix later to maint). + (merge ac05222b31 ah/patch-id-doc later to maint). diff --git a/Documentation/RelNotes/2.14.1.txt b/Documentation/RelNotes/2.14.1.txt new file mode 100644 index 00000000000000..9403340f7f50a9 --- /dev/null +++ b/Documentation/RelNotes/2.14.1.txt @@ -0,0 +1,4 @@ +Git v2.14.1 Release Notes +========================= + +This release forward-ports the fix for "ssh://..." URL from Git v2.7.6 diff --git a/Documentation/RelNotes/2.14.2.txt b/Documentation/RelNotes/2.14.2.txt new file mode 100644 index 00000000000000..bec9186adefe6e --- /dev/null +++ b/Documentation/RelNotes/2.14.2.txt @@ -0,0 +1,105 @@ +Git v2.14.2 Release Notes +========================= + +Fixes since v2.14.1 +------------------- + + * Because recent Git for Windows do come with a real msgfmt, the + build procedure for git-gui has been updated to use it instead of a + hand-rolled substitute. + + * "%C(color name)" in the pretty print format always produced ANSI + color escape codes, which was an early design mistake. They now + honor the configuration (e.g. "color.ui = never") and also tty-ness + of the output medium. + + * The http.{sslkey,sslCert} configuration variables are to be + interpreted as a pathname that honors "~[username]/" prefix, but + weren't, which has been fixed. + + * Numerous bugs in walking of reflogs via "log -g" and friends have + been fixed. + + * "git commit" when seeing an totally empty message said "you did not + edit the message", which is clearly wrong. The message has been + corrected. + + * When a directory is not readable, "gitweb" fails to build the + project list. Work this around by skipping such a directory. + + * A recently added test for the "credential-cache" helper revealed + that EOF detection done around the time the connection to the cache + daemon is torn down were flaky. This was fixed by reacting to + ECONNRESET and behaving as if we got an EOF. + + * Some versions of GnuPG fail to kill gpg-agent it auto-spawned + and such a left-over agent can interfere with a test. Work it + around by attempting to kill one before starting a new test. + + * "git log --tag=no-such-tag" showed log starting from HEAD, which + has been fixed---it now shows nothing. + + * The "tag.pager" configuration variable was useless for those who + actually create tag objects, as it interfered with the use of an + editor. A new mechanism has been introduced for commands to enable + pager depending on what operation is being carried out to fix this, + and then "git tag -l" is made to run pager by default. + + * "git push --recurse-submodules $there HEAD:$target" was not + propagated down to the submodules, but now it is. + + * Commands like "git rebase" accepted the --rerere-autoupdate option + from the command line, but did not always use it. This has been + fixed. + + * "git clone --recurse-submodules --quiet" did not pass the quiet + option down to submodules. + + * "git am -s" has been taught that some input may end with a trailer + block that is not Signed-off-by: and it should refrain from adding + an extra blank line before adding a new sign-off in such a case. + + * "git svn" used with "--localtime" option did not compute the tz + offset for the timestamp in question and instead always used the + current time, which has been corrected. + + * Memory leaks in a few error codepaths have been plugged. + + * bash 4.4 or newer gave a warning on NUL byte in command + substitution done in "git stash"; this has been squelched. + + * "git grep -L" and "git grep --quiet -L" reported different exit + codes; this has been corrected. + + * When handshake with a subprocess filter notices that the process + asked for an unknown capability, Git did not report what program + the offending subprocess was running. This has been corrected. + + * "git apply" that is used as a better "patch -p1" failed to apply a + taken from a file with CRLF line endings to a file with CRLF line + endings. The root cause was because it misused convert_to_git() + that tried to do "safe-crlf" processing by looking at the index + entry at the same path, which is a nonsense---in that mode, "apply" + is not working on the data in (or derived from) the index at all. + This has been fixed. + + * Killing "git merge --edit" before the editor returns control left + the repository in a state with MERGE_MSG but without MERGE_HEAD, + which incorrectly tells the subsequent "git commit" that there was + a squash merge in progress. This has been fixed. + + * "git archive" did not work well with pathspecs and the + export-ignore attribute. + + * "git cvsserver" no longer is invoked by "git daemon" by default, + as it is old and largely unmaintained. + + * Various Perl scripts did not use safe_pipe_capture() instead of + backticks, leaving them susceptible to end-user input. They have + been corrected. + +Also contains various documentation updates and code clean-ups. + +Credits go to joernchen for finding the +unsafe constructs in "git cvsserver", and to Jeff King at GitHub for +finding and fixing instances of the same issue in other scripts. diff --git a/Documentation/RelNotes/2.14.3.txt b/Documentation/RelNotes/2.14.3.txt new file mode 100644 index 00000000000000..977c9e857c0ef3 --- /dev/null +++ b/Documentation/RelNotes/2.14.3.txt @@ -0,0 +1,99 @@ +Git v2.14.3 Release Notes +========================= + +Fixes since v2.14.2 +------------------- + + * A helper function to read a single whole line into strbuf + mistakenly triggered OOM error at EOF under certain conditions, + which has been fixed. + + * In addition to "cc: # cruft", "cc: a@dd.re.ss # cruft" + was taught to "git send-email" as a valid way to tell it that it + needs to also send a carbon copy to in the trailer + section. + + * Fix regression to "gitk --bisect" by a recent update. + + * Unlike "git commit-tree < file", "git commit-tree -F file" did not + pass the contents of the file verbatim and instead completed an + incomplete line at the end, if exists. The latter has been updated + to match the behaviour of the former. + + * "git archive", especially when used with pathspec, stored an empty + directory in its output, even though Git itself never does so. + This has been fixed. + + * API error-proofing which happens to also squelch warnings from GCC. + + * "git gc" tries to avoid running two instances at the same time by + reading and writing pid/host from and to a lock file; it used to + use an incorrect fscanf() format when reading, which has been + corrected. + + * The test linter has been taught that we do not like "echo -e". + + * Code cmp.std.c nitpick. + + * "git describe --match" learned to take multiple patterns in v2.13 + series, but the feature ignored the patterns after the first one + and did not work at all. This has been fixed. + + * "git cat-file --textconv" started segfaulting recently, which + has been corrected. + + * The built-in pattern to detect the "function header" for HTML did + not match

..

elements without any attributes, which has + been fixed. + + * "git mailinfo" was loose in decoding quoted printable and produced + garbage when the two letters after the equal sign are not + hexadecimal. This has been fixed. + + * The documentation for '-X