diff --git a/.cirrus.yml b/.cirrus.yml deleted file mode 100644 index fef04a38402fee..00000000000000 --- a/.cirrus.yml +++ /dev/null @@ -1,24 +0,0 @@ -env: - CIRRUS_CLONE_DEPTH: 1 - -freebsd_task: - env: - GIT_PROVE_OPTS: "--timer --jobs 10" - GIT_TEST_OPTS: "--no-chain-lint --no-bin-wrappers" - GIT_SKIP_TESTS: t7815.12 - MAKEFLAGS: -j4 - DEFAULT_TEST_TARGET: prove - DEFAULT_UNIT_TEST_TARGET: unit-tests-prove - DEVELOPER: 1 - freebsd_instance: - image_family: freebsd-14-3 - 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 test unit-tests' diff --git a/.clang-format b/.clang-format deleted file mode 100644 index 86b4fe33e5cd98..00000000000000 --- a/.clang-format +++ /dev/null @@ -1,228 +0,0 @@ -# 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 - -# While we do want to enforce a character limit of 80 characters, we often -# allow lines to overflow that limit to prioritize readability. Setting a -# character limit here with penalties has been finicky and creates too many -# false positives. -# -# NEEDSWORK: It would be nice if we can find optimal settings to ensure we -# can re-enable the limit here. -ColumnLimit: 0 - -# 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: ControlStatementsExceptControlMacros - -# 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 - -# Don't sort #include's -SortIncludes: false - -# Remove optional braces of control statements (if, else, for, and while) -# according to the LLVM coding style. This avoids braces on simple -# single-statement bodies of statements but keeps braces if one side of -# if/else if/.../else cascade has multi-statement body. -RemoveBracesLLVM: true diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 82e121a41754b5..00000000000000 --- a/.editorconfig +++ /dev/null @@ -1,20 +0,0 @@ -[*] -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,bash,perl,pl,pm,txt,adoc},config.mak.*,Makefile}] -indent_style = tab -tab_width = 8 - -[templates/hooks/*.sample] -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 556322be01b4a8..3d84236f419016 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,21 +1 @@ -* whitespace=trail,space -*.[ch] whitespace=indent,trail,space,incomplete diff=cpp -*.sh whitespace=indent,trail,space,incomplete 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 -CODE_OF_CONDUCT.md -whitespace -/Documentation/**/*.adoc text eol=lf whitespace=trail,space,incomplete -/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.adoc conflict-marker-size=32 -/Documentation/git-merge-file.adoc conflict-marker-size=32 -/Documentation/gitk.adoc conflict-marker-size=32 -/Documentation/user-manual.adoc conflict-marker-size=32 -/t/t????-*.sh conflict-marker-size=32 -/t/unit-tests/clar/test/expected/* whitespace=-blank-at-eof -/templates/hooks/*.sample whitespace=indent,trail,space,incomplete text eol=lf +whats-cooking.txt diff=whatscooking diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md deleted file mode 100644 index 93042128d60d21..00000000000000 --- a/.github/CONTRIBUTING.md +++ /dev/null @@ -1,23 +0,0 @@ -## 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](https://git-scm.com/docs/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/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index 37654cdfd7abcf..00000000000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,10 +0,0 @@ -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. - -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/workflows/check-style.yml b/.github/workflows/check-style.yml deleted file mode 100644 index 19a145d4ad0c5a..00000000000000 --- a/.github/workflows/check-style.yml +++ /dev/null @@ -1,34 +0,0 @@ -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@v5 - 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 deleted file mode 100644 index 928fd4cfe2456d..00000000000000 --- a/.github/workflows/check-whitespace.yml +++ /dev/null @@ -1,32 +0,0 @@ -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@v5 - 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 deleted file mode 100644 index cfa17d394a7dbc..00000000000000 --- a/.github/workflows/coverity.yml +++ /dev/null @@ -1,167 +0,0 @@ -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@v5 - - 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: - CI_JOB_IMAGE: ${{ 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="$PATH:$RUNNER_TEMP/cov-analysis/bin" && - cov-configure --gcc && - if ! cov-build --dir cov-int make - then - cat cov-int/build-log.txt - exit 1 - fi - - 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 deleted file mode 100644 index 95e55134bdbed4..00000000000000 --- a/.github/workflows/l10n.yml +++ /dev/null @@ -1,111 +0,0 @@ -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@v6 - 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 deleted file mode 100644 index 826f2f5d3a6a88..00000000000000 --- a/.github/workflows/main.yml +++ /dev/null @@ -1,515 +0,0 @@ -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@v8 - 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@v5 - - 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@v5 - 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@v6 - 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}} + 1)) 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@v5 - 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 - concurrency: - group: vs-build-${{ github.ref }} - cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} - steps: - - uses: actions/checkout@v5 - - uses: git-for-windows/setup-git-for-windows-sdk@v1 - - name: initialize vcpkg - uses: actions/checkout@v5 - 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 - - name: generate Visual Studio solution - shell: bash - run: | - cmake `pwd`/contrib/buildsystems/ -DCMAKE_PREFIX_PATH=`pwd`/compat/vcbuild/vcpkg/installed/x64-windows \ - -DNO_GETTEXT=YesPlease -DPERL_TESTS=OFF -DPYTHON_TESTS=OFF -DCURL_NO_CURL_CMAKE=ON - - name: MSBuild - run: msbuild git.sln -property:Configuration=Release -property:Platform=x64 -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@v5 - with: - name: vs-artifacts - 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@v6 - with: - name: vs-artifacts - 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}} + 1)) 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@v5 - with: - name: failed-tests-windows-vs-${{ matrix.nr }} - path: ${{env.FAILED_TEST_ARTIFACTS}} - - windows-meson-build: - name: win+Meson build - needs: ci-config - if: needs.ci-config.outputs.enabled == 'yes' - runs-on: windows-latest - concurrency: - group: windows-meson-build-${{ github.ref }} - cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} - steps: - - uses: actions/checkout@v5 - - uses: actions/setup-python@v6 - - name: Set up dependencies - shell: pwsh - run: pip install meson ninja - - name: Setup - shell: pwsh - run: meson setup build --vsenv -Dbuildtype=release -Dperl=disabled -Dcredential_helpers=wincred - - name: Compile - shell: pwsh - run: meson compile -C build - - name: Upload build artifacts - uses: actions/upload-artifact@v5 - with: - name: windows-meson-artifacts - path: build - windows-meson-test: - name: win+Meson test - runs-on: windows-latest - needs: [ci-config, windows-meson-build] - strategy: - fail-fast: false - matrix: - nr: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] - concurrency: - group: windows-meson-test-${{ matrix.nr }}-${{ github.ref }} - cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} - steps: - - uses: actions/checkout@v5 - - uses: actions/setup-python@v6 - - name: Set up dependencies - shell: pwsh - run: pip install meson ninja - - name: Download build artifacts - uses: actions/download-artifact@v6 - with: - name: windows-meson-artifacts - path: build - - name: Test - shell: bash - run: ci/run-test-slice-meson.sh build $((${{matrix.nr}} + 1)) 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-meson-${{ 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: osx-clang - cc: clang - pool: macos-14 - - jobname: osx-reftable - cc: clang - pool: macos-14 - - jobname: osx-gcc - cc: gcc-13 - pool: macos-14 - - jobname: osx-meson - cc: clang - pool: macos-14 - env: - CC: ${{matrix.vector.cc}} - CC_PACKAGE: ${{matrix.vector.cc_package}} - jobname: ${{matrix.vector.jobname}} - CI_JOB_IMAGE: ${{matrix.vector.pool}} - TEST_OUTPUT_DIRECTORY: ${{github.workspace}}/t - runs-on: ${{matrix.vector.pool}} - steps: - - uses: actions/checkout@v5 - - 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@v5 - 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 - CI_JOB_IMAGE: ubuntu-latest - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v5 - - 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-sha256 - image: ubuntu:rolling - cc: clang - - jobname: linux-reftable - image: ubuntu:rolling - cc: clang - - jobname: linux-TEST-vars - image: ubuntu:20.04 - cc: gcc - cc_package: gcc-8 - - jobname: linux-breaking-changes - cc: gcc - image: ubuntu:rolling - - jobname: fedora-breaking-changes-meson - image: fedora:latest - - jobname: linux-leaks - image: ubuntu:rolling - cc: gcc - - jobname: linux-reftable-leaks - image: ubuntu:rolling - cc: gcc - - jobname: linux-asan-ubsan - image: ubuntu:rolling - cc: clang - - jobname: linux-meson - image: ubuntu:rolling - cc: gcc - - jobname: linux-musl-meson - image: alpine:latest - # Supported until 2025-04-02. - - jobname: linux32 - image: i386/ubuntu:focal - # A RHEL 8 compatible distro. Supported until 2029-05-31. - - jobname: almalinux-8 - image: almalinux:8 - # Supported until 2026-08-31. - - jobname: debian-11 - image: debian:11 - env: - jobname: ${{matrix.vector.jobname}} - CC: ${{matrix.vector.cc}} - CI_JOB_IMAGE: ${{matrix.vector.image}} - CUSTOM_PATH: /custom - 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 - - name: install git in container - run: | - if command -v git - then - : # nothing to do - elif command -v apk - then - apk add --update git - elif command -v dnf - then - dnf -yq update && dnf -yq install git - else - apt-get -q update && apt-get -q -y install git - fi - - uses: actions/checkout@v5 - - run: ci/install-dependencies.sh - - run: useradd builder --create-home - - run: chown -R builder . - - run: chmod a+w $GITHUB_ENV && sudo --preserve-env --set-home --user=builder ci/run-build-and-tests.sh - - name: print test failures - if: failure() && env.FAILED_TEST_ARTIFACTS != '' - run: sudo --preserve-env --set-home --user=builder ci/print-test-failures.sh - - name: Upload failed tests' directories - if: failure() && env.FAILED_TEST_ARTIFACTS != '' - uses: actions/upload-artifact@v5 - 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 - CI_JOB_IMAGE: ubuntu-22.04 - 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@v5 - - run: ci/install-dependencies.sh - - run: ci/run-static-analysis.sh - - run: ci/check-directional-formatting.bash - rust-analysis: - needs: ci-config - if: needs.ci-config.outputs.enabled == 'yes' - env: - jobname: RustAnalysis - CI_JOB_IMAGE: ubuntu:rolling - runs-on: ubuntu-latest - container: ubuntu:rolling - concurrency: - group: rust-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-rust-checks.sh - sparse: - needs: ci-config - if: needs.ci-config.outputs.enabled == 'yes' - env: - jobname: sparse - CI_JOB_IMAGE: ubuntu-22.04 - runs-on: ubuntu-22.04 - concurrency: - group: sparse-${{ github.ref }} - cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} - steps: - - uses: actions/checkout@v5 - - 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 - CI_JOB_IMAGE: ubuntu-latest - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v5 - - run: ci/install-dependencies.sh - - run: ci/test-documentation.sh diff --git a/.gitignore b/.gitignore index 24635cf2d6f4a3..4d8f04330c062f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,261 +1,3 @@ -/fuzz_corpora -/target/ -/Cargo.lock -/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 -/git -/git-add -/git-am -/git-annotate -/git-apply -/git-archimport -/git-archive -/git-backfill -/git-bisect -/git-blame -/git-branch -/git-bugreport -/git-bundle -/git-cat-file -/git-check-attr -/git-check-ignore -/git-check-mailmap -/git-check-ref-format -/git-checkout -/git-checkout--worker -/git-checkout-index -/git-cherry -/git-cherry-pick -/git-clean -/git-clone -/git-column -/git-commit -/git-commit-graph -/git-commit-tree -/git-config -/git-count-objects -/git-credential -/git-credential-cache -/git-credential-cache--daemon -/git-credential-store -/git-cvsexportcommit -/git-cvsimport -/git-cvsserver -/git-daemon -/git-diagnose -/git-diff -/git-diff-files -/git-diff-index -/git-diff-pairs -/git-diff-tree -/git-difftool -/git-difftool--helper -/git-describe -/git-fast-export -/git-fast-import -/git-fetch -/git-fetch-pack -/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-history -/git-hook -/git-http-backend -/git-http-fetch -/git-http-push -/git-imap-send -/git-index-pack -/git-init -/git-init-db -/git-interpret-trailers -/git-instaweb -/git-last-modified -/git-log -/git-ls-files -/git-ls-remote -/git-ls-tree -/git-mailinfo -/git-mailsplit -/git-maintenance -/git-merge -/git-merge-base -/git-merge-index -/git-merge-file -/git-merge-tree -/git-merge-octopus -/git-merge-one-file -/git-merge-ours -/git-merge-recursive -/git-merge-resolve -/git-merge-subtree -/git-mergetool -/git-mergetool--lib -/git-mktag -/git-mktree -/git-multi-pack-index -/git-mv -/git-name-rev -/git-notes -/git-p4 -/git-pack-redundant -/git-pack-objects -/git-pack-refs -/git-patch-id -/git-prune -/git-prune-packed -/git-pull -/git-push -/git-quiltimport -/git-range-diff -/git-read-tree -/git-rebase -/git-receive-pack -/git-reflog -/git-refs -/git-remote -/git-remote-http -/git-remote-https -/git-remote-ftp -/git-remote-ftps -/git-remote-fd -/git-remote-ext -/git-repack -/git-replace -/git-replay -/git-repo -/git-request-pull -/git-rerere -/git-reset -/git-restore -/git-rev-list -/git-rev-parse -/git-revert -/git-rm -/git-send-email -/git-send-pack -/git-sh-i18n -/git-sh-i18n--envsubst -/git-sh-setup -/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-svn -/git-switch -/git-symbolic-ref -/git-tag -/git-unpack-file -/git-unpack-objects -/git-update-index -/git-update-ref -/git-update-server-info -/git-upload-archive -/git-upload-pack -/git-var -/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.* -/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 -*.gcov -/coverage-untested-functions -/cover_db/ -/cover_db_html/ -*+ -/config.mak -/autom4te.cache -/config.cache -/config.log -/config.status -/config.mak.autogen -/config.mak.append -/configure -/.vscode/ -/tags -/TAGS -/cscope* -/compile_commands.json -/.cache/ -*.hcc -*.obj -*.lib -*.sln -*.sp -*.suo -*.ncb -*.vcproj -*.user -*.idb -*.pdb -*.ilk -*.iobj -*.ipdb -*.dll -.vs/ -Debug/ -Release/ -/UpgradeLog*.htm -/git.VC.VC.opendb -/git.VC.db -*.dSYM -/contrib/buildsystems/out -/contrib/libgit-rs/target -/contrib/libgit-sys/target +/AT.log +/AT.log.bak +/AT.build-logs/ diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml deleted file mode 100644 index 83ec786c5a49d0..00000000000000 --- a/.gitlab-ci.yml +++ /dev/null @@ -1,284 +0,0 @@ -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-sha256 - image: ubuntu:rolling - CC: clang - - jobname: linux-reftable - image: ubuntu:rolling - CC: clang - - jobname: linux-breaking-changes - image: ubuntu:20.04 - CC: gcc - - jobname: fedora-breaking-changes-meson - image: fedora:latest - - jobname: linux-TEST-vars - image: ubuntu:20.04 - CC: gcc - CC_PACKAGE: gcc-8 - - jobname: linux-leaks - image: ubuntu:rolling - CC: gcc - - jobname: linux-reftable-leaks - image: ubuntu:rolling - CC: gcc - - jobname: linux-asan-ubsan - image: ubuntu:rolling - CC: clang - - jobname: linux-musl-meson - image: alpine:latest - - jobname: linux32 - image: i386/ubuntu:20.04 - - jobname: linux-meson - image: ubuntu:rolling - CC: gcc - artifacts: - paths: - - t/failed-test-artifacts - reports: - junit: build/meson-logs/testlog.junit.xml - 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-15-xcode-16 - CC: clang - - jobname: osx-reftable - image: macos-15-xcode-16 - CC: clang - - jobname: osx-meson - image: macos-15-xcode-16 - CC: clang - artifacts: - paths: - - t/failed-test-artifacts - reports: - junit: build/meson-logs/testlog.junit.xml - when: on_failure - -.windows_before_script: &windows_before_script - # Disabling realtime monitoring fails on some of the runners, but it - # significantly speeds up test execution in the case where it works. We thus - # try our luck, but ignore any failures. - - Set-MpPreference -DisableRealtimeMonitoring $true; $true - -build:mingw64: - stage: build - tags: - - saas-windows-medium-amd64 - variables: - NO_PERL: 1 - before_script: - - *windows_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: - - *windows_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 - -.msvc-meson: - variables: - TEST_OUTPUT_DIRECTORY: "C:/Git-Test" - tags: - - saas-windows-medium-amd64 - before_script: - - *windows_before_script - - choco install -y git meson ninja rust-ms - - Import-Module $env:ChocolateyInstall\helpers\chocolateyProfile.psm1 - - refreshenv - - New-Item -Path $env:TEST_OUTPUT_DIRECTORY -ItemType Directory - -build:msvc-meson: - extends: .msvc-meson - stage: build - script: - - meson setup build --vsenv -Dperl=disabled -Dbackend_max_links=1 -Dcredential_helpers=wincred -Dtest_output_directory="$TEST_OUTPUT_DIRECTORY" - - meson compile -C build - artifacts: - paths: - - build - -test:msvc-meson: - extends: .msvc-meson - stage: test - timeout: 6h - needs: - - job: "build:msvc-meson" - artifacts: true - script: - - | - & "C:/Program Files/Git/usr/bin/bash.exe" -l -c 'ci/run-test-slice-meson.sh build $CI_NODE_INDEX $CI_NODE_TOTAL' - after_script: - - | - if ($env:CI_JOB_STATUS -ne "success") { - & "C:/Program Files/Git/usr/bin/bash.exe" -l -c 'ci/print-test-failures.sh' - Move-Item -Path "$env:TEST_OUTPUT_DIRECTORY/failed-test-artifacts" -Destination t/ - } - parallel: 10 - artifacts: - paths: - - t/failed-test-artifacts - reports: - junit: build/meson-logs/testlog.junit.xml - when: on_failure - -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 - -rust-analysis: - image: ubuntu:rolling - stage: analyze - needs: [ ] - variables: - jobname: RustAnalysis - before_script: - - ./ci/install-dependencies.sh - script: - - ./ci/run-rust-checks.sh - -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 deleted file mode 100644 index cbeebdab7a5e2c..00000000000000 --- a/.gitmodules +++ /dev/null @@ -1,4 +0,0 @@ -[submodule "sha1collisiondetection"] - path = sha1collisiondetection - url = https://github.com/cr-marcstevens/sha1collisiondetection.git - branch = master diff --git a/.mailmap b/.mailmap deleted file mode 100644 index c2e3939beb286d..00000000000000 --- a/.mailmap +++ /dev/null @@ -1,314 +0,0 @@ -# -# This list is used by git-shortlog to fix a few botched name translations -# in the git archive, either because the author's full name was messed up -# and/or not always written the same way, making contributions from the -# same person appearing not to be so. -# - - -Alejandro R. Sedeño -Alex Bennée -Alex Riesen -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 -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 -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 -Frank Lichtenheld -Fredrik Kuivinen -Frédéric Heitzmann -Garry Dolley -Glen Choo -Greg Hurrell -Greg Hurrell -Greg Price -Greg Price -Heiko Voigt -H. Merijn Brand H.Merijn Brand -H. Peter Anvin -H. Peter Anvin -H. Peter Anvin -H. Peter Anvin -Han-Wen Nienhuys Han-Wen Nienhuys -Horst H. von Brand -J. Bruce Fields -J. Bruce Fields -J. Bruce Fields -Jakub Narębski -James Y Knight -# The 2 following authors are probably the same person, -# but both emails bounce. -Jason McMullan -Jason McMullan -Jason Riedy -Jason Riedy -Jay Soffian -Jean-Noël Avila Jean-Noel Avila -Jean-Noël Avila Jean-Noël AVILA -Jean-Noël Avila Jean-Noel Avila -Jean-Noël Avila Jean-Noël AVILA -Jean-Noël Avila Jean-Noël Avila via GitGitGadget -Jeff King -Jeff Muizelaar -Jens Axboe -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 -John 'Warthog9' Hawley -Jon Loeliger -Jon Loeliger -Jon Seymour -Jonathan Nieder -Jonathan del Strother -Jonathan Tan -Josh Triplett -Josh Triplett -Julian Phillips -Junio C Hamano -Junio C Hamano -Junio C Hamano -Junio C Hamano -Junio C Hamano -Junio C Hamano -Junio C Hamano -Kaartic Sivaraam -Karl Wiberg Karl Hasselström -Karl Wiberg -Karsten Blees -Karsten Blees -Kay Sievers -Kay Sievers -Kazuki Saitoh kazuki saitoh -Keith Cascio -Kent Engstrom -Kevin Leung -Kirill Smelkov -Kirill Smelkov -Knut Franke -Lars Doelle -Lars Doelle -Lars Noschinski -Li Hong -Linus Arver -Linus Torvalds -Linus Torvalds -Linus Torvalds -Linus Torvalds -Linus Torvalds -Linus Torvalds -Lukas Sandström -Marc Khouzam -Marc-André Lureau -Marco Costalba -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 S. Tsirkin -Michael S. Tsirkin -Michael S. Tsirkin -Michael W. Olson -Michael Witten -Michael Witten -Michal Rokos -Michele Ballabio -Miklos Vajna -Namhyung Kim -Namhyung Kim -Nanako Shiraishi -Nanako Shiraishi -Nelson Elhage -Nelson Elhage -Nguyễn Thái Ngọc Duy -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 -Peter Baumann -Peter Krefting -Peter Krefting -Petr Baudis -Petr Baudis -Phil Hord -Phil Hord -Philip Jägenstedt -Philip Oakley # secondary -Philipp A. Hartmann -Philippe Bruhat -Phillip Wood -Phillip Wood -Ralf Thielow -Ramsay Jones -Ramkumar Ramachandra -Randall S. Becker -René Scharfe -René Scharfe Rene Scharfe -Richard Hansen -Richard Hansen -Robert Fitzsimons -Robert Shearman -Robert Zeh -Robin Rosenberg -Rutger Nijlunsing -Rutger Nijlunsing -Ryan Anderson -Salikh Zakirov -Sam Vilain -Sam Vilain sam@vilain.net -Santi Béjar -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 -Steven Walter -Steven Walter -Sven Verdoolaege -Sven Verdoolaege -SZEDER Gábor -Tao Qingyun <845767657@qq.com> -Tay Ray Chuan -Ted Percival -Theodore Ts'o -Thomas Ackermann -Thomas Rast -Thomas Rast -Thomas Rast -Tian Yuchen -Timo Hirvonen -Toby Allsopp -Tom Grennan -Tommi Virtanen -Tommi Virtanen -Tommy Thorn -Tony Luck -Tor Arne Vestbø -Trần Ngọc Quân Tran Ngoc Quan -Trent Piepho -Trent Piepho -Uwe Kleine-König -Uwe Kleine-König -Uwe Kleine-König -Uwe Kleine-König -Ville Skyttä -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 -İsmail Dönmez diff --git a/.tsan-suppressions b/.tsan-suppressions deleted file mode 100644 index 5ba86d68459e61..00000000000000 --- a/.tsan-suppressions +++ /dev/null @@ -1,16 +0,0 @@ -# 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/Announce b/Announce new file mode 100755 index 00000000000000..8ac01306e347cc --- /dev/null +++ b/Announce @@ -0,0 +1,186 @@ +#!/bin/sh +# Announcement message skelton +# +: ${MASTER=master} + +tmpbase=/var/tmp/git-announce.$$ +trap 'rm -f $tmpbase.*' 0 +branch=${1?branch} +previous=${2?previous} +commit=${3-"$1"} + +relname=$(git describe "$commit") && +vername=$(expr "$relname" : 'v\(.*\)') || exit $? + +git rev-parse --verify "$previous" >/dev/null || exit $? + +case "$branch" in +maint) + kind="The latest maintenance release" ;; +mainto/* | maint-[0-9]*) + kind="A maintenance release" ;; +$MASTER) + kind="The latest feature release" ;; +esac + +case "$vername" in +*-rc[0-9]*) + rpmroot=testing + case "$vername" in + *-rc0) + kind="An early preview release" + ;; + *) + kind="A release candidate" + ;; + esac + for_testing=" for testing" + ;; +*) + for_testing= + rpmroot='RPMS/$arch' + ;; +esac + +vername=$(echo "$vername" | tr "-" ".") + +people () { + git shortlog -s --no-merges \ + --group=author \ + --group=trailer:co-authored-by \ + --group=trailer:reviewed-by \ + --group=trailer:mentored-by \ + --group=trailer:helped-by \ + --group=trailer:tested-by \ + --group=trailer:reported-by \ + "$@" | + sed -e 's/^[ 0-9]*[ ]//' -e 's/$/,/' | + sort -u +} + +people "$previous" >"$tmpbase.prev" +people "$previous..$commit" >"$tmpbase.this" + +comm -12 "$tmpbase.prev" "$tmpbase.this" >"$tmpbase.old" +comm -13 "$tmpbase.prev" "$tmpbase.this" >"$tmpbase.new" + +all=$(wc -l <"$tmpbase.this") +new=$(wc -l <"$tmpbase.new") +cnt=$(git rev-list --no-merges "$previous..$commit" | wc -l) + +cat <, + git-packagers@googlegroups.com +Bcc: lwn@lwn.net, gitster@pobox.com +Subject: [ANNOUNCE] Git $relname + +EOF + +( + echo "$kind Git $relname is now available$for_testing at the usual places." + if test "$branch" = $MASTER + then + cat <<-EOF + It is comprised of $cnt non-merge commits since $previous, + contributed by $all people, $new of which are new faces [*]. + EOF + fi +) | fmt -68 + +cat < - - Christian Couder - - Junio C Hamano - - Taylor Blau - -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.0, available at -[https://www.contributor-covenant.org/version/2/0/code_of_conduct.html][v2.0]. - -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.0]: https://www.contributor-covenant.org/version/2/0/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/COPYING b/COPYING deleted file mode 100644 index 536e55524db72b..00000000000000 --- a/COPYING +++ /dev/null @@ -1,360 +0,0 @@ - - Note that the only valid version of the GPL as far as this project - is concerned is _this_ particular version of the license (ie v2, not - v2.2 or v3.x or whatever), unless explicitly otherwise stated. - - HOWEVER, in order to allow a migration to GPLv3 if that seems like - a good idea, I also ask that people involved with the project make - their preferences known. In particular, if you trust me to make that - decision, you might note so in your copyright message, ie something - like - - This file is licensed under the GPL v2, or a later version - at the discretion of Linus. - - might avoid issues. But we can also just decide to synchronize and - contact all copyright holders on record if/when the occasion arises. - - Linus Torvalds - ----------------------------------------- - - GNU GENERAL PUBLIC LICENSE - Version 2, June 1991 - - Copyright (C) 1989, 1991 Free Software Foundation, Inc., - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -License is intended to guarantee your freedom to share and change free -software--to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Lesser General Public License instead.) You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - - We protect your rights with two steps: (1) copyright the software, and -(2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - - Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - - The precise terms and conditions for copying, distribution and -modification follow. - - GNU GENERAL PUBLIC LICENSE - TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - - 0. This License applies to any program or other work which contains -a notice placed by the copyright holder saying it may be distributed -under the terms of this General Public License. The "Program", below, -refers to any such program or work, and a "work based on the Program" -means either the Program or any derivative work under copyright law: -that is to say, a work containing the Program or a portion of it, -either verbatim or with modifications and/or translated into another -language. (Hereinafter, translation is included without limitation in -the term "modification".) Each licensee is addressed as "you". - -Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running the Program is not restricted, and the output from the Program -is covered only if its contents constitute a work based on the -Program (independent of having been made by running the Program). -Whether that is true depends on what the Program does. - - 1. You may copy and distribute verbatim copies of the Program's -source code as you receive it, in any medium, provided that you -conspicuously and appropriately publish on each copy an appropriate -copyright notice and disclaimer of warranty; keep intact all the -notices that refer to this License and to the absence of any warranty; -and give any other recipients of the Program a copy of this License -along with the Program. - -You may charge a fee for the physical act of transferring a copy, and -you may at your option offer warranty protection in exchange for a fee. - - 2. You may modify your copy or copies of the Program or any portion -of it, thus forming a work based on the Program, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - - a) You must cause the modified files to carry prominent notices - stating that you changed the files and the date of any change. - - b) You must cause any work that you distribute or publish, that in - whole or in part contains or is derived from the Program or any - part thereof, to be licensed as a whole at no charge to all third - parties under the terms of this License. - - c) If the modified program normally reads commands interactively - when run, you must cause it, when started running for such - interactive use in the most ordinary way, to print or display an - announcement including an appropriate copyright notice and a - notice that there is no warranty (or else, saying that you provide - a warranty) and that users may redistribute the program under - these conditions, and telling the user how to view a copy of this - License. (Exception: if the Program itself is interactive but - does not normally print such an announcement, your work based on - the Program is not required to print an announcement.) - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Program, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Program, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Program. - -In addition, mere aggregation of another work not based on the Program -with the Program (or with a work based on the Program) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - - 3. You may copy and distribute the Program (or a work based on it, -under Section 2) in object code or executable form under the terms of -Sections 1 and 2 above provided that you also do one of the following: - - a) Accompany it with the complete corresponding machine-readable - source code, which must be distributed under the terms of Sections - 1 and 2 above on a medium customarily used for software interchange; or, - - b) Accompany it with a written offer, valid for at least three - years, to give any third party, for a charge no more than your - cost of physically performing source distribution, a complete - machine-readable copy of the corresponding source code, to be - distributed under the terms of Sections 1 and 2 above on a medium - customarily used for software interchange; or, - - c) Accompany it with the information you received as to the offer - to distribute corresponding source code. (This alternative is - allowed only for noncommercial distribution and only if you - received the program in object code or executable form with such - an offer, in accord with Subsection b above.) - -The source code for a work means the preferred form of the work for -making modifications to it. For an executable work, complete source -code means all the source code for all modules it contains, plus any -associated interface definition files, plus the scripts used to -control compilation and installation of the executable. However, as a -special exception, the source code distributed need not include -anything that is normally distributed (in either source or binary -form) with the major components (compiler, kernel, and so on) of the -operating system on which the executable runs, unless that component -itself accompanies the executable. - -If distribution of executable or object code is made by offering -access to copy from a designated place, then offering equivalent -access to copy the source code from the same place counts as -distribution of the source code, even though third parties are not -compelled to copy the source along with the object code. - - 4. You may not copy, modify, sublicense, or distribute the Program -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense or distribute the Program is -void, and will automatically terminate your rights under this License. -However, parties who have received copies, or rights, from you under -this License will not have their licenses terminated so long as such -parties remain in full compliance. - - 5. You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Program or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Program (or any work based on the -Program), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Program or works based on it. - - 6. Each time you redistribute the Program (or any work based on the -Program), the recipient automatically receives a license from the -original licensor to copy, distribute or modify the Program subject to -these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties to -this License. - - 7. If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Program at all. For example, if a patent -license would not permit royalty-free redistribution of the Program by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Program. - -If any portion of this section is held invalid or unenforceable under -any particular circumstance, the balance of the section is intended to -apply and the section as a whole is intended to apply in other -circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system, which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - - 8. If the distribution and/or use of the Program is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Program under this License -may add an explicit geographical distribution limitation excluding -those countries, so that distribution is permitted only in or among -countries not thus excluded. In such case, this License incorporates -the limitation as if written in the body of this License. - - 9. The Free Software Foundation may publish revised and/or new versions -of the General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies a version number of this License which applies to it and "any -later version", you have the option of following the terms and conditions -either of that version or of any later version published by the Free -Software Foundation. If the Program does not specify a version number of -this License, you may choose any version ever published by the Free Software -Foundation. - - 10. If you wish to incorporate parts of the Program into other free -programs whose distribution conditions are different, write to the author -to ask for permission. For software which is copyrighted by the Free -Software Foundation, write to the Free Software Foundation; we sometimes -make exceptions for this. Our decision will be guided by the two goals -of preserving the free status of all derivatives of our free software and -of promoting the sharing and reuse of software generally. - - NO WARRANTY - - 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY -FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN -OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES -PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED -OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS -TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE -PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, -REPAIR OR CORRECTION. - - 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR -REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING -OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED -TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY -YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER -PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGES. - - END OF TERMS AND CONDITIONS - - How to Apply These Terms to Your New Programs - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the "copyright" line and a pointer to where the full notice is found. - - - Copyright (C) - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License along - with this program; if not, write to the Free Software Foundation, Inc., - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. - -Also add information on how to contact you by electronic and paper mail. - -If the program is interactive, make it output a short notice like this -when it starts in an interactive mode: - - Gnomovision version 69, Copyright (C) year name of author - Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - -The hypothetical commands `show w' and `show c' should show the appropriate -parts of the General Public License. Of course, the commands you use may -be called something other than `show w' and `show c'; they could even be -mouse-clicks or menu items--whatever suits your program. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a "copyright disclaimer" for the program, if -necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright interest in the program - `Gnomovision' (which makes passes at compilers) written by James Hacker. - - , 1 April 1989 - Ty Coon, President of Vice - -This General Public License does not permit incorporating your program into -proprietary programs. If your program is a subroutine library, you may -consider it more useful to permit linking proprietary applications with the -library. If this is what you want to do, use the GNU Lesser General -Public License instead of this License. diff --git a/CannedResponses b/CannedResponses new file mode 100644 index 00000000000000..68d2df8632cad2 --- /dev/null +++ b/CannedResponses @@ -0,0 +1,148 @@ +---------------------------------------------------------------- +[the structure of a log message] + +The usual way to compose a log message of this project is to + + - Give an observation on how the current system works in the + present tense (so no need to say "Currently X is Y", or + "Previously X was Y" to describe the state before your change; + just "X is Y" is enough), and discuss what you perceive as a + problem in it. + + - Propose a solution (optional---often, problem description + trivially leads to an obvious solution in reader's minds). + + - Give commands to somebody editing the codebase to "make it so", + instead of saying "This commit does X". + +in this order. + +To those who have been intimately following the discussion, it often +is understandable without some of the above, but we are not writing +for those who review the patches. We are primarily writing for future +readers of "git log" who are not aware of the review discussion we +have on list, so we should give something to prepare them by setting +the stage and stating the objective first, before going into how the +patch solved it. + +------------------------------------------------------------------------ +[polish your history before sending] + +We frown upon a patch series that makes mistakes in an earlier step, +only to fix them in a later step. The "git rebase -i" command helps +us pretend to be more perfect developers than we actually are, +whipping your patch series into a shape that builds one small step +on top of another in a logical succession. Such a patch series is +easier to understand than a history that faithfully records all the +stumbles the developer made until they reached the final solution. + +------------------------------------------------------------------------ +[not just respond, update the patches] + +Not limited to this one, but when a reviewer says "this is not +clear", it is often not a request to only clarify something, which +is clear to any intelligent user of the end product, to a clueless +reviewer, whose intelligence is below the target audience, in an +e-mail response. It is pointing out that the end product, either the +patch text or the proposed log message, is not clear to target +audience and needs update. + +We would expect a review comment to be at least responded to either +rebut or admit the issues raised. It may be that a reviewer's point +were missing the mark and the patches themselves were perfectly +fine. + +But all other cases, even when the reviewer's comment were missing +the mark, such a confusion may have been the result of the patch +text or the proposed log message being unclear. Of course, the +review comments may have been pointing out an actionable issue. +They would hopefully lead to an improved version of the patches +posted sometime later, so that we can conclude a topic and move +ahead. +---------------------------------------------------------------- +[not just reroll, but respond to reviews] + +After getting review comments but before sending a new iteration of +your patches, do respond to the review e-mails directly to develop a +dialog between you as the author and your reviewers. + +A new iteration of a patch is harder to read without such a dialog +telling reviewers what the author thought after getting suggestions in +earlier reviews. + +Did they agree and took the suggestion? Did they disagree but took +the suggestion anyway, and if so why did they think the suggested +changes are not good? Did they disagree and did not take the +suggestion and if so why? They changed the code but not in the way +suggested in the review, but why the new way was thought to be better +than both the original and the reviewer input? + +These are natural questions reviewers want to get answered, and some +of them can be answered by reading a new iteration of patch (e.g., did +they or did they not update the patch?) but not others (e.g., why did +they or did they not do so?). +---------------------------------------------------------------- +[make us come to you, begging] + +I've seen from time to time people ask "I am thinking of doing this; +will a patch be accepted? If so, I'll work on it." before showing +any work, and my response always has been: + + (1) We don't know how useful and interesting your contribution would + be for our audience, until we see it; and + + (2) If you truly believe in your work (find it useful, find writing + it fun, etc.), that would be incentive enough for you to work + on it, whether or not the result will land in my tree. You + should instead aim for something so brilliant that we would + come to you begging for your permission to include it in our + project. + +---------------------------------------------------------------- +[mailing list is the primary place] + +One thing to note is that I do not respond to a pull request in private, +and Github pull request, as I understand it, is very private in nature. +The patches are to be reviewed on the main mailing list first. + +It's OK to say "these patches are also available in my repository at +Github whose URL is this" in the commentary part of the final submission +message after the list reaches consensus that your change is a good thing, +and that may reduce the chance of mistakes when I accept the patches +especially if the series is large, so I am not saying that repositories +people have Github have no value to my workflow. But it will not come +into the picture before the final submission phase. + +---------------------------------------------------------------- +[going incremental after hitting next] + +Once a commit hits 'next', it gets improved only by piling incremental +updates on top with explanation. The idea is: if all of us thought it +has seen enough eyeballs and is good enough for 'next', yet we later +find there was something we all missed, that is worth a separate +explanation, e.g., "The primary motivation behind the series is still +good, but for such and such reasons we missed this case we are +fixing." + +Unless it turns out that the approach was fundamentally wrong and such +an incremental update boils down to almost reverting the earlier one +entirely and replacing it with the newer one. In such a case, we do +revert the earlier and replace it with the newer, in 'next'. + +---------------------------------------------------------------- +[do not iterate too quickly] + +After sending your patches out, it would be nice to give potential +reviewers at least 24 hours to ensure people anywhere on the globe +have a chance to comment, and a chance for you to respond to them, +before sending your next iteration. + +When responding to a review comment that causes you to drastically +change the course of the series, it is nice to give potential +reviewers at least 24 hours to ensure they have a chance to voice +their opinions, before sending an updated series based on that +comment, because suggested changes in such a comment may be +controversial and deserve discussion. After seeing you spend some +time already to adjust to one opinion on such a discussion, others may +feel discouraged to make you redo your series again even whey they +think the suggested changes are not taking us in the right direction. diff --git a/Cargo.toml b/Cargo.toml deleted file mode 100644 index 2f51bf5d5ff5f8..00000000000000 --- a/Cargo.toml +++ /dev/null @@ -1,10 +0,0 @@ -[package] -name = "gitcore" -version = "0.1.0" -edition = "2018" -rust-version = "1.49.0" - -[lib] -crate-type = ["staticlib"] - -[dependencies] diff --git a/CheckPush b/CheckPush new file mode 100755 index 00000000000000..e79f364e8e7247 --- /dev/null +++ b/CheckPush @@ -0,0 +1,84 @@ +#!/bin/dash + +MASTER=master + +for range in $( + { + git for-each-ref --format='%(refname)' refs/heads/maint-\* | + perl -e ' + sub compare_dotted_version { + my (@ours) = split(/\./, $_[0]); + my (@theirs) = split(/\./, $_[1]); + my ($i, $diff); + + for ($i = 0; $i < @ours && $i < @theirs; $i++) { + $diff = $ours[$i] - $theirs[$i]; + return $diff if ($diff); + } + return 1 if ($i < @ours); + return -1 if ($i < @theirs); + return 0; + } + my @maint = (); + while () { + next unless s|^refs/heads/||; + chomp; + my ($v) = ($_ =~ /^maint-(.*)$/); + push @maint, [$v, $_]; + } + for (map { $_->[1] } + sort { compare_dotted_version($a->[0], $b->[0]) } + @maint) { + print "$_\n"; + } + ' && + cat <<-EOF + maint + $MASTER + next + EOF + } | + { + prev_branch= + while read branch + do + if test -n "$prev_branch" + then + echo "$branch..$prev_branch" + fi + prev_branch=$branch + done + } +) seen..jch +do + lg=$(git log --oneline "$range") + if test -n "$lg" + then + echo "*** $range ***" + echo "$lg" + fi +done + +if ! next_equiv=$(git rev-parse --verify 'jch^{/^### match next}' 2>/dev/null) || + ! git diff --stat --exit-code next $next_equiv +then + next_tree=$(git rev-parse next^{tree}) && + next_equiv=$(git rev-list --first-parent $MASTER^..seen | + xargs -n1 sh -c ' + echo $(git rev-parse $1^{tree}) $1 + ' - | sed -n -e "s/^$next_tree //p" + ) +fi + +if test -n "$next_equiv" +then + jch=$(git rev-list --first-parent $MASTER..jch | wc -l) && + seen=$(git rev-list --first-parent $MASTER..seen | wc -l) && + next=$(git rev-list --first-parent $MASTER..$next_equiv | wc -l) && + if test $jch -le $next + then + echo "$MASTER..$jch..jch..$next..next..$seen..seen" + else + echo "$MASTER..$next..next..$jch..jch..$seen..seen" + fi +fi diff --git a/Checklist.txt b/Checklist.txt new file mode 100644 index 00000000000000..3a7d3ee6859571 --- /dev/null +++ b/Checklist.txt @@ -0,0 +1,66 @@ +Release checklist. + + : shell; THIS=1.5.2.3 + : shell; PREV=1.5.2.2 + + - The usual build/test, locally and on k.org private. + + - "git shortlog -s v$PREV..maint" and update .mailmap + + - Update Documentation/RelNotes/$THIS.txt, make sure RelNotes + points to it, update GIT-VERSION-GEN. + + - Proofread RelNotes. + + - Commit "GIT $THIS"; create signed tag v$THIS with "GIT + $THIS". + + - Push to builder: + + : shell; git push builders tag $THIS + : shell; git push builders + + - Build on builder; take resulting RPM tarball to k.org; + + : builder; cd git.git + : builder; git checkout maint && Meta/DoKernelOrg maint + : builder; cd .. && scp $THIS.tar master.kernel.org:. + + - Push to k.org private: + + : shell; git push ko-private tag $THIS + : shell; git push ko-private + + - Build on k.org: + + : k.org; cd rpms && tar xf ../$THIS.tar + : k.org; cd ../git.git + : k.org; git checkout maint && Meta/DoKernelOrg maint + + - Merge in 'maint' to 'master', and update the "stale" list of + documents in 'master': + + : shell; git checkout master + : shell; git merge maint + : shell; edit Documentation/git.txt + : shell; git commit + + - Push the results out: + + : shell; git push ko tag $THIS + : shell; git push repo tag $THIS + : shell; git push ko + : shell; git push repo + + - Extract the documentation on k.org: + + : k.org; cd /pub/software/scm/git/docs + : k.org; mkdir v$THIS && cd v$THIS + : k.org; tar zxf ../../git-htmldocs-$THIS.tar.gz + + - Prepare and send out the announce: + + : shell; Meta/Announce maint $PREV + + - Update Meta/MaintNotes and send it out (when releasing from + 'master'). diff --git a/Count b/Count new file mode 100755 index 00000000000000..39fd77176d7022 --- /dev/null +++ b/Count @@ -0,0 +1,14 @@ +#!/bin/sh + +: ${asof=${1-now}} + +: ${lasttag=${2-$( + git tag --list 'v*.0' --sort=version:tag | tail -n 1 + )}} + +for r in "$lasttag..master@{$asof}" \ + "master@{$asof}..next@{$asof}" \ + "master@{$asof}..seen@{$asof}" +do + echo "$r $(git rev-list --count --no-merges $r)" +done diff --git a/Documentation/.gitignore b/Documentation/.gitignore deleted file mode 100644 index dd54cc768a250c..00000000000000 --- a/Documentation/.gitignore +++ /dev/null @@ -1,20 +0,0 @@ -*.xml -*.html -*.[1-8] -*.made -*.texi -*.pdf -git.info -gitman.info -howto-index.adoc -doc.dep -cmds-*.adoc -mergetools-*.adoc -SubmittingPatches.adoc -tmp-doc-diff/ -tmp-meson-diff/ -GIT-ASCIIDOCFLAGS -/.build/ -/GIT-EXCLUDED-PROGRAMS -/asciidoc.conf -/asciidoctor-extensions.rb diff --git a/Documentation/BreakingChanges.adoc b/Documentation/BreakingChanges.adoc deleted file mode 100644 index f814450d2f65ac..00000000000000 --- a/Documentation/BreakingChanges.adoc +++ /dev/null @@ -1,335 +0,0 @@ -= 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, prepared over long -time. - -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 also have a CI job 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. - -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>, -. - -* The default storage format for references in newly created repositories will - be changed from "files" to "reftable". The "reftable" format provides - multiple advantages over the "files" format: -+ - ** It is impossible to store two references that only differ in casing on - case-insensitive filesystems with the "files" format. This issue is common - on Windows and macOS platforms. As the "reftable" backend does not use - filesystem paths to encode reference names this problem goes away. - ** Similarly, macOS normalizes path names that contain unicode characters, - which has the consequence that you cannot store two names with unicode - characters that are encoded differently with the "files" backend. Again, - this is not an issue with the "reftable" backend. - ** Deleting references with the "files" backend requires Git to rewrite the - complete "packed-refs" file. In large repositories with many references - this file can easily be dozens of megabytes in size, in extreme cases it - may be gigabytes. The "reftable" backend uses tombstone markers for - deleted references and thus does not have to rewrite all of its data. - ** Repository housekeeping with the "files" backend typically performs - all-into-one repacks of references. This can be quite expensive, and - consequently housekeeping is a tradeoff between the number of loose - references that accumulate and slow down operations that read references, - and compressing those loose references into the "packed-refs" file. The - "reftable" backend uses geometric compaction after every write, which - amortizes costs and ensures that the backend is always in a - well-maintained state. - ** Operations that write multiple references at once are not atomic with the - "files" backend. Consequently, Git may see in-between states when it reads - references while a reference transaction is in the process of being - committed to disk. - ** Writing many references at once is slow with the "files" backend because - every reference is created as a separate file. The "reftable" backend - significantly outperforms the "files" backend by multiple orders of - magnitude. - ** The reftable backend uses a binary format with prefix compression for - reference names. As a result, the format uses less space compared to the - "packed-refs" file. -+ -Users that get immediate benefit from the "reftable" backend could continue to -opt-in to the "reftable" format manually by setting the "init.defaultRefFormat" -config. But defaults matter, and we think that overall users will have a better -experience with less platform-specific quirks when they use the new backend by -default. -+ -A prerequisite for this change is that the ecosystem is ready to support the -"reftable" format. Most importantly, alternative implementations of Git like -JGit, libgit2 and Gitoxide need to support it. - -* In new repositories, the default branch name will be `main`. We have been - warning that the default name will change since 675704c74dd (init: - provide useful advice about init.defaultBranch, 2020-12-11). The new name - matches the default branch name used in new repositories by many of the - big Git forges. - -* Git will require Rust as a mandatory part of the build process. While Git - already started to adopt Rust in Git 2.49, all parts written in Rust are - optional for the time being. This includes: -+ - ** The Rust wrapper around libgit.a that is part of "contrib/" and which has - been introduced in Git 2.49. - ** Subsystems that have an alternative implementation in Rust to test - interoperability between our C and Rust codebase. - ** Newly written features that are not mission critical for a fully functional - Git client. -+ -These changes are meant as test balloons to allow distributors of Git to prepare -for Rust becoming a mandatory part of the build process. There will be multiple -milestones for the introduction of Rust: -+ --- -1. Initially, with Git 2.52, support for Rust will be auto-detected by Meson and - disabled in our Makefile so that the project can sort out the initial - infrastructure. -2. In Git 2.53, both build systems will default-enable support for Rust. - Consequently, builds will break by default if Rust is not available on the - build host. The use of Rust can still be explicitly disabled via build - flags. -3. In Git 3.0, the build options will be removed and support for Rust is - mandatory. --- -+ -You can explicitly ask both Meson and our Makefile-based system to enable Rust -by saying `meson configure -Drust=enabled` and `make WITH_RUST=YesPlease`, -respectively. -+ -The Git project will declare the last version before Git 3.0 to be a long-term -support release. This long-term release will receive important bug fixes for at -least four release cycles and security fixes for six release cycles. The Git -project will hand over maintainership of the long-term release to distributors -in case they need to extend the life of that long-term release even further. -Details of how this long-term release will be handed over to the community will -be discussed once the Git project decides to stop officially supporting it. -+ -We will evaluate the impact on downstream distributions before making Rust -mandatory in Git 3.0. If we see that the impact on downstream distributions -would be significant, we may decide to defer this change to a subsequent minor -release. This evaluation will also take into account our own experience with -how painful it is to keep Rust an optional component. - -=== 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>, - -* Support for storing shorthands for remote URLs in "$GIT_COMMON_DIR/branches/" - and "$GIT_COMMON_DIR/remotes/" has been long superseded by storing remotes in - the repository configuration. -+ -The mechanism has originally been introduced in f170e4b39d ([PATCH] fetch/pull: -short-hand notation for remote repositories., 2005-07-16) and was superseded by -6687f8fea2 ([PATCH] Use .git/remote/origin, not .git/branches/origin., -2005-08-20), where we switched from ".git/branches/" to ".git/remotes/". That -commit already mentions an upcoming deprecation of the ".git/branches/" -directory, and starting with a1d4aa7424 (Add repository-layout document., -2005-09-01) we have also marked this layout as deprecated. Eventually we also -started to migrate away from ".git/remotes/" in favor of config-based remotes, -and we have marked the directory as legacy in 3d3d282146 (Documentation: -Grammar correction, wording fixes and cleanup, 2011-08-23) -+ -As our documentation mentions, these directories are unlikely to be used in -modern repositories and most users aren't even aware of these mechanisms. They -have been deprecated for almost 20 years and 14 years respectively, and we are -not aware of any active users that have complained about this deprecation. -Furthermore, the ".git/branches/" directory is nowadays misleadingly named and -may cause confusion as "branches" are almost exclusively used in the context of -references. -+ -These features will be removed. - -* Support for "--stdin" option in the "name-rev" command was - deprecated (and hidden from the documentation) in the Git 2.40 - timeframe, in preference to its synonym "--annotate-stdin". Git 3.0 - removes the support for "--stdin" altogether. - -* The git-whatchanged(1) command has outlived its usefulness more than - 10 years ago, and takes more keystrokes to type than its rough - equivalent `git log --raw`. We have nominated the command for - removal, have changed the command to refuse to work unless the - `--i-still-use-this` option is given, and asked the users to report - when they do so. -+ -The command will be removed. - -* Support for `core.commentString=auto` has been deprecated and will - be removed in Git 3.0. -+ -cf. - -* Support for `core.preferSymlinkRefs=true` has been deprecated and will be - removed in Git 3.0. Writing symbolic refs as symbolic links will be phased - out in favor of using plain files using the textual representation of - symbolic refs. -+ -Symbolic references were initially always stored as a symbolic link. This was -changed in 9b143c6e15 (Teach update-ref about a symbolic ref stored in a -textfile., 2005-09-25), where a new textual symref format was introduced to -store those symbolic refs in a plain file. In 9f0bb90d16 -(core.prefersymlinkrefs: use symlinks for .git/HEAD, 2006-05-02), the Git -project switched the default to use the textual symrefs in favor of symbolic -links. -+ -The migration away from symbolic links has happened almost 20 years ago by now, -and there is no known reason why one should prefer them nowadays. Furthermore, -symbolic links are not supported on some platforms. -+ -Note that only the writing side for such symbolic links is deprecated. Reading -such symbolic links is still supported for now. - -== 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 deleted file mode 100644 index 4992e52093efdc..00000000000000 --- a/Documentation/CodingGuidelines +++ /dev/null @@ -1,1019 +0,0 @@ -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." - We live in the real world. - - - However, we often say "Let's stay away from that construct, - it's not even in POSIX". - - - In spite of the above two rules, we sometimes say "Although - this is not in POSIX, it (is so convenient | makes the code - much more readable | has other good characteristics) and - practically all the platforms we care about support it, so - let's use it". - - Again, we live in the real world, and it is sometimes a - judgement call, the decision based more on real world - constraints people face than what the paper standard says. - - - Fixing style violations while working on a real change as a - preparatory clean-up step is good, but otherwise avoid useless code - churn for the sake of conforming to the style. - - "Once it _is_ in the tree, it's not really worth the patch noise to - go and fix it up." - 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). - - - A label "NEEDSWORK:" followed by a description of the things to - be done is a way to leave in-code comments to document design - decisions yet to be made. 80% of the work to resolve a NEEDSWORK - comment is to decide if it still makes sense to do so, since the - situation around the codebase may have changed since the comment - was written. It can be a very valid change to remove an existing - NEEDSWORK comment without doing anything else, with the commit log - message describing a good argument why it does not make sense to do - the thing the NEEDSWORK comment mentioned. - -Make your code readable and sensible, and don't try to be clever. - -As for more concrete guidelines, just imitate the existing code -(this is a good guideline, no matter which project you are -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 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 are some language -specific ones. Note that Documentation/ToolsForGit.adoc document -has a collection of tips to help you use some external tools -to conform to these guidelines. - -For shell scripts specifically (not exhaustive): - - - We use tabs for indentation. - - - Case arms are indented at the same depth as case and esac lines, - like this: - - case "$variable" in - pattern1) - do this - ;; - pattern2) - do that - ;; - esac - - - Redirection operators should be written with space before, but no - space after them. In other words, write 'echo test >"$file"' - instead of 'echo test> $file' or 'echo test > $file'. Note that - even though it is not required by POSIX to double-quote the - redirection target in a variable (as shown above), our code does so - because some versions of bash issue a warning without the quotes. - - (incorrect) - cat hello > world < universe - echo hello >$world - - (correct) - cat hello >world "$world" - - - We prefer $( ... ) for command substitution; unlike ``, it - properly nests. It should have been the way Bourne spelled - it from day one, but unfortunately isn't. - - - 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 parsable and its exit code - is not reliable across platforms. - - - We use POSIX compliant parameter substitutions and avoid bashisms; - namely: - - - We use ${parameter-word} and its [-=?+] siblings, and their - colon'ed "unset or null" form. - - - We use ${parameter#word} and its [#%] siblings, and their - doubled "longest matching" form. - - - No "Substring Expansion" ${parameter:offset:length}. - - - No shell arrays. - - - No pattern replacement ${parameter/pattern/string}. - - - We use Arithmetic Expansion $(( ... )). - - - We do not use Process Substitution <(list) or >(list). - - - Do not write control structures on a single line with semicolon. - "then" should be on the next line for if statements, and "do" - should be on the next line for "while" and "for". - - (incorrect) - if test -f hello; then - do this - fi - - (correct) - if test -f hello - then - 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 - functions. - - - We prefer a space between the function name and the parentheses, - and no space inside the parentheses. The opening "{" should also - be on the same line. - - (incorrect) - my_function(){ - ... - - (correct) - my_function () { - ... - - - As to use of grep, stick to a subset of BRE (namely, no \{m,n\}, - [::], [==], or [..]) for portability. - - - We do not use \{m,n\}; - - - 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 - of BRE -- making them accessible from BRE is a GNU extension). - - - Use Git's gettext wrappers in git-sh-i18n to make the user - interface translatable. See "Marking strings for translation" in - po/README. - - - We do not write our "test" command with "-a" and "-o" and use "&&" - or "||" to concatenate multiple "test" commands instead, because - the use of "-a/-o" is often error-prone. E.g. - - test -n "$x" -a "$a" = "$b" - - is buggy and breaks when $x is "=", but - - test -n "$x" && test "$a" = "$b" - - 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. 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. - - . since late 2021 with 44ba10d6, we have had variables declared in - the for loop "for (int i = 0; i < 10; i++)". - - . since late 2023 with 8277dbe987 we have been using the bool type - from . - - C99 features we have test balloons for: - - . since late 2024 with v2.48.0-rc0~20, we have test balloons for - compound literal syntax, e.g., (struct foo){ .member = value }; - our hope is that no platforms we care about have trouble using - them, and officially adopt its wider use in mid 2026. Do not add - more use of the syntax until that happens. - - 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. - - - Do not explicitly initialize global variables to 0 or NULL; - instead, let BSS take care of the zero initialization. - - - NULL pointers shall be written as NULL, not as 0. - - - When declaring pointers, the star sides with the variable - name, i.e. "char *string", not "char* string" or - "char * string". This makes it easier to understand code - like "char *string, c;". - - - Use whitespace around operators and keywords, but not inside - parentheses and not around functions. So: - - while (condition) - func(bar + 1); - - and not: - - 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. 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. - - - Try to make your code understandable. You may put comments - in, but comments invariably tend to stale out when the code - they were describing changes. Often splitting a function - into two makes the intention of the code much clearer. - - - Multi-line comments include their delimiters on separate lines from - the text. E.g. - - /* - * A very long - * multi-line comment. - */ - - Note however that a comment that explains a translatable string to - translators uses a convention of starting with a magic token - "TRANSLATORS: ", e.g. - - /* - * 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."); - - We do not use // comments. - - - Double negation is often harder to understand than no negation - at all. - - - There are two schools of thought when it comes to comparison, - especially inside a loop. Some people prefer to have the less stable - value on the left hand side and the more stable value on the right hand - side, e.g. if you have a loop that counts variable i down to the - lower bound, - - while (i > lower_bound) { - do something; - i--; - } - - Other people prefer to have the textual order of values match the - actual order of values in their comparison, so that they can - mentally draw a number line from left to right and place these - values in order, i.e. - - while (lower_bound < i) { - do something; - i--; - } - - Both are valid, and we use both. However, the more "stable" the - stable side becomes, the more we tend to prefer the former - (comparison with a constant, "i > 0", is an extreme example). - Just do not mix styles in the same part of the code and mimic - existing styles in the neighbourhood. - - - There are two schools of thought when it comes to splitting a long - logical line into multiple lines. Some people push the second and - subsequent lines far enough to the right with tabs and align them: - - if (the_beginning_of_a_very_long_expression_that_has_to || - span_more_than_a_single_line_of || - the_source_text) { - ... - - while other people prefer to align the second and the subsequent - lines with the column immediately inside the opening parenthesis, - with tabs and spaces, following our "tabstop is always a multiple - of 8" convention: - - if (the_beginning_of_a_very_long_expression_that_has_to || - span_more_than_a_single_line_of || - the_source_text) { - ... - - Both are valid, and we use both. Again, just do not mix styles in - the same part of the code and mimic existing styles in the - neighbourhood. - - - When splitting a long logical line, some people change line before - a binary operator, so that the result looks like a parse tree when - you turn your head 90-degrees counterclockwise: - - if (the_beginning_of_a_very_long_expression_that_has_to - || span_more_than_a_single_line_of_the_source_text) { - - while other people prefer to leave the operator at the end of the - line: - - if (the_beginning_of_a_very_long_expression_that_has_to || - span_more_than_a_single_line_of_the_source_text) { - - Both are valid, but we tend to use the latter more, unless the - expression gets fairly complex, in which case the former tends to - be easier to read. Again, just do not mix styles in the same part - of the code and mimic existing styles in the neighbourhood. - - - When splitting a long logical line, with everything else being - equal, it is preferable to split after the operator at higher - level in the parse tree. That is, this is more preferable: - - if (a_very_long_variable * that_is_used_in + - a_very_long_expression) { - ... - - than - - if (a_very_long_variable * - that_is_used_in + a_very_long_expression) { - ... - - - Some clever tricks, like using the !! operator with arithmetic - constructs, can be extremely confusing to others. Avoid them, - unless there is a compelling reason to use them. - - - Use the API. No, really. We have a strbuf (variable length - string), several arrays with the ALLOC_GROW() macro, a - 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 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 - changed and discussed. Many Git commands started out like - that, and a few are still scripts. - - - Avoid introducing a new dependency into Git. This means you - usually should stay away from scripting languages not already - used in the Git core command set (unless your command is clearly - separate from it, such as an importer to convert random-scm-X - repositories to Git). - - - When we pass pair to functions, we should try to - pass them in that order. - - - 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 reinitializing - the structure for immediate reuse, and without freeing the structure - itself. - - - `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. - - - Bit fields should be defined without a space around the colon. E.g. - - unsigned my_field:1; - unsigned other_field:1; - unsigned field_with_longer_name:1; - - - When a function `F` accepts flags, those flags should be defined as `enum - F_flags`. Individual flag definitions should start with `F` and be in - all-uppercase letters. Flag values should be represented via bit shifts. - E.g. - - enum frobnicate_flags { - FROBNICATE_FOO = (1 << 0), - FROBNICATE_BAR = (1 << 1), - }; - - int frobnicate(enum frobnicate_flags flags); - - - Array names should be named in the singular form if the individual items are - subject of use. E.g.: - - char *dog[] = ...; - walk_dog(dog[0]); - walk_dog(dog[1]); - - Cases where the array is employed as a whole rather than as its unit parts, - the plural forms is preferable. E.g: - - char *dogs[] = ...; - walk_all_dogs(dogs); - -For Perl programs: - - - Most of the C guidelines above apply. - - - We try to support Perl 5.8.1 and later ("use Perl 5.008001"). - - - use strict and use warnings are strongly preferred. - - - Don't overuse statement modifiers unless using them makes the - result easier to follow. - - ... do something ... - do_this() unless (condition); - ... do something else ... - - is more readable than: - - ... do something ... - unless (condition) { - do_this(); - } - ... do something else ... - - *only* when the condition is so rare that do_this() will be almost - always called. - - - We try to avoid assignments inside "if ()" conditions. - - - Learn and use Git.pm if you need that functionality. - -For Python scripts: - - - We follow PEP-8 (https://peps.python.org/pep-0008/). - - - 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. - - -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 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. - - 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. - - 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: - - Most (if not all) of the documentation pages are written in the - AsciiDoc format in *.adoc files (e.g. Documentation/git.adoc), and - processed into HTML and manpages (e.g. git.html and git.1 in the - same directory). - - The documentation liberally mixes US and UK English (en_US/UK) - norms for spelling and grammar, which is somewhat unfortunate. - In an ideal world, it would have been better if it consistently - used only one and not the other, and we would have picked en_US - (if you wish to correct the English of some of the existing - 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: - __ - __ - -Characters are also surrounded by underscores: - _LF_, _CR_, _CR_/_LF_, _NUL_, _EOF_ - - 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. - - When documenting multiple related `git config` variables, place them on - a separate line instead of separating them by commas. For example, do - not write this: - `core.var1`, `core.var2`:: - Description common to `core.var1` and `core.var2`. - -Instead write this: - `core.var1`:: - `core.var2`:: - Description common to `core.var1` and `core.var2`. - -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: - - Possibility of multiple occurrences is indicated by three dots: - ... - (One or more of .) - - Optional parts are enclosed in square brackets: - [...] - (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 - brackets.) - - [...] - (Zero or more of . Note that the dots are inside, not - outside the brackets.) - - 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 - it clear that "..." pertains to both and .) - - [(-p )...] - (Any number of option -p, each with one argument.) - - git remote set-head (-a|-d|) - (One and only one of "-a", "-d" or "" _must_ (no square - brackets) be provided.) - - And a somewhat more contrived example: - --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]] - Here "=" is outside the brackets, because "--diff-filter=" is a - valid usage. "*" has its own pair of brackets, because it can - (optionally) be specified only when one or more of the letters is - also provided. - - A note on notation: - Use 'git' (all lowercase) when talking about commands i.e. something - the user would type into a shell and use 'Git' (uppercase first letter) - when talking about the version control system and its properties. - - 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 - the former, the part that should not get substituted must be - quoted/escaped. diff --git a/Documentation/DecisionMaking.adoc b/Documentation/DecisionMaking.adoc deleted file mode 100644 index b43c472ae598ed..00000000000000 --- a/Documentation/DecisionMaking.adoc +++ /dev/null @@ -1,74 +0,0 @@ -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 deleted file mode 100644 index 2699f0b24af192..00000000000000 --- a/Documentation/Makefile +++ /dev/null @@ -1,570 +0,0 @@ -# The default target of this Makefile is... -all:: - -# 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 %,%.adoc,$(EXCLUDED_PROGRAMS)) \ - $(addsuffix .adoc, $(ARTICLES) $(SP_ARTICLES)), \ - $(wildcard git-*.adoc)) -MAN1_TXT += git.adoc -MAN1_TXT += gitk.adoc -MAN1_TXT += gitweb.adoc -MAN1_TXT += scalar.adoc - -# man5 / man7 guides (note: new guides should also be added to command-list.txt) -MAN5_TXT += gitattributes.adoc -MAN5_TXT += gitformat-bundle.adoc -MAN5_TXT += gitformat-chunk.adoc -MAN5_TXT += gitformat-commit-graph.adoc -MAN5_TXT += gitformat-index.adoc -MAN5_TXT += gitformat-loose.adoc -MAN5_TXT += gitformat-pack.adoc -MAN5_TXT += gitformat-signature.adoc -MAN5_TXT += githooks.adoc -MAN5_TXT += gitignore.adoc -MAN5_TXT += gitmailmap.adoc -MAN5_TXT += gitmodules.adoc -MAN5_TXT += gitprotocol-capabilities.adoc -MAN5_TXT += gitprotocol-common.adoc -MAN5_TXT += gitprotocol-http.adoc -MAN5_TXT += gitprotocol-pack.adoc -MAN5_TXT += gitprotocol-v2.adoc -MAN5_TXT += gitrepository-layout.adoc -MAN5_TXT += gitweb.conf.adoc - -MAN7_TXT += gitcli.adoc -MAN7_TXT += gitcore-tutorial.adoc -MAN7_TXT += gitcredentials.adoc -MAN7_TXT += gitcvs-migration.adoc -MAN7_TXT += gitdatamodel.adoc -MAN7_TXT += gitdiffcore.adoc -MAN7_TXT += giteveryday.adoc -MAN7_TXT += gitfaq.adoc -MAN7_TXT += gitglossary.adoc -MAN7_TXT += gitpacking.adoc -MAN7_TXT += gitnamespaces.adoc -MAN7_TXT += gitremote-helpers.adoc -MAN7_TXT += gitrevisions.adoc -MAN7_TXT += gitsubmodules.adoc -MAN7_TXT += gittutorial-2.adoc -MAN7_TXT += gittutorial.adoc -MAN7_TXT += gitworkflows.adoc - -HOWTO_TXT += $(wildcard howto/*.adoc) - -DOC_DEP_TXT += $(wildcard *.adoc) -DOC_DEP_TXT += $(wildcard config/*.adoc) -DOC_DEP_TXT += $(wildcard includes/*.adoc) - -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 %.adoc,%.xml,$(MAN_TXT)) -MAN_HTML = $(patsubst %.adoc,%.html,$(MAN_TXT)) -GIT_MAN_REF = master - -OBSOLETE_HTML += everyday.html -OBSOLETE_HTML += git-remote-helpers.html - -ARTICLES += howto-index -ARTICLES += git-tools -ARTICLES += git-bisect-lk2009 -# with their own formatting rules. -SP_ARTICLES += user-manual -SP_ARTICLES += howto/new-command -SP_ARTICLES += howto/revert-branch-rebase -SP_ARTICLES += howto/using-merge-subtree -SP_ARTICLES += howto/using-signed-tag-in-pull-request -SP_ARTICLES += howto/use-git-daemon -SP_ARTICLES += howto/update-hook-example -SP_ARTICLES += howto/setup-git-server-over-http -SP_ARTICLES += howto/separating-topic-branches -SP_ARTICLES += howto/revert-a-faulty-merge -SP_ARTICLES += howto/recover-corrupted-blob-object -SP_ARTICLES += howto/recover-corrupted-object-harder -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 %.adoc,%,$(filter-out technical/api-index-skel.adoc technical/api-index.adoc, $(wildcard technical/api-*.adoc))) -SP_ARTICLES += $(API_DOCS) - -TECH_DOCS += BreakingChanges -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/commit-graph -TECH_DOCS += technical/directory-rename-detection -TECH_DOCS += technical/hash-function-transition -TECH_DOCS += technical/large-object-promisors -TECH_DOCS += technical/long-running-process-protocol -TECH_DOCS += technical/multi-pack-index -TECH_DOCS += technical/packfile-uri -TECH_DOCS += technical/pack-heuristics -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/remembering-renames -TECH_DOCS += technical/repository-version -TECH_DOCS += technical/rerere -TECH_DOCS += technical/scalar -TECH_DOCS += technical/send-pack-pipeline -TECH_DOCS += technical/shallow -TECH_DOCS += technical/sparse-checkout -TECH_DOCS += technical/sparse-index -TECH_DOCS += technical/trivial-merge -TECH_DOCS += technical/unambiguous-types -TECH_DOCS += technical/unit-tests -SP_ARTICLES += $(TECH_DOCS) -SP_ARTICLES += technical/api-index - -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 %.adoc,%.1,$(filter $(MAN_FILTER),$(MAN1_TXT))) -DOC_MAN5 = $(patsubst %.adoc,%.5,$(filter $(MAN_FILTER),$(MAN5_TXT))) -DOC_MAN7 = $(patsubst %.adoc,%.7,$(filter $(MAN_FILTER),$(MAN7_TXT))) - -prefix ?= $(HOME) -bindir ?= $(prefix)/bin -htmldir ?= $(prefix)/share/doc/git-doc -infodir ?= $(prefix)/share/info -pdfdir ?= $(prefix)/share/doc/git-doc -mandir ?= $(prefix)/share/man -man1dir = $(mandir)/man1 -man5dir = $(mandir)/man5 -man7dir = $(mandir)/man7 -# DESTDIR = - -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 = -INSTALL ?= install -RM ?= rm -f -MAN_REPO = ../../git-manpages -HTML_REPO = ../../git-htmldocs - -MAKEINFO = makeinfo -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 - --include ../config.mak.autogen --include ../config.mak - -# 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) - -ifndef NO_MAN_BOLD_LITERAL -XMLTO_EXTRA += -m manpage-bold-literal.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 -# stylesheets simply ignore this parameter. -# -# Distros may want to use MAN_BASE_URL=file:///path/to/git/docs/ -# or similar. -ifndef MAN_BASE_URL -MAN_BASE_URL = file://$(htmldir)/ -endif -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 - -ifdef WITH_BREAKING_CHANGES -ASCIIDOC_EXTRA += -awith-breaking-changes -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)' -endif - -ifdef DEFAULT_EDITOR -DEFAULT_EDITOR_SQ = $(subst ','\'',$(DEFAULT_EDITOR)) -ASCIIDOC_EXTRA += -a 'git-default-editor=$(DEFAULT_EDITOR_SQ)' -endif - -all:: html man - -html: $(DOC_HTML) - -man: man1 man5 man7 -man1: $(DOC_MAN1) -man5: $(DOC_MAN5) -man7: $(DOC_MAN7) - -info: git.info gitman.info - -pdf: user-manual.pdf - -install: install-man - -install-man: man - $(INSTALL) -d -m 755 $(DESTDIR)$(man1dir) - $(INSTALL) -d -m 755 $(DESTDIR)$(man5dir) - $(INSTALL) -d -m 755 $(DESTDIR)$(man7dir) - $(INSTALL) -m 644 $(DOC_MAN1) $(DESTDIR)$(man1dir) - $(INSTALL) -m 644 $(DOC_MAN5) $(DESTDIR)$(man5dir) - $(INSTALL) -m 644 $(DOC_MAN7) $(DESTDIR)$(man7dir) - -install-info: info - $(INSTALL) -d -m 755 $(DESTDIR)$(infodir) - $(INSTALL) -m 644 git.info gitman.info $(DESTDIR)$(infodir) - if test -r $(DESTDIR)$(infodir)/dir; then \ - $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) git.info ;\ - $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) gitman.info ;\ - else \ - echo "No directory found in $(DESTDIR)$(infodir)" >&2 ; \ - fi - -install-pdf: pdf - $(INSTALL) -d -m 755 $(DESTDIR)$(pdfdir) - $(INSTALL) -m 644 user-manual.pdf $(DESTDIR)$(pdfdir) - -install-html: html - '$(SHELL_PATH_SQ)' ./install-webdoc.sh $(DESTDIR)$(htmldir) - -mergetools_txt = mergetools-diff.adoc mergetools-merge.adoc - -# -# Determine "include::" file references in asciidoc files. -# -docdep_prereqs = \ - $(mergetools_txt) \ - cmd-list.made $(cmds_txt) - -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.adoc \ - cmds-ancillarymanipulators.adoc \ - cmds-mainporcelain.adoc \ - cmds-plumbinginterrogators.adoc \ - cmds-plumbingmanipulators.adoc \ - cmds-synchingrepositories.adoc \ - cmds-synchelpers.adoc \ - cmds-guide.adoc \ - cmds-developerinterfaces.adoc \ - cmds-userinterfaces.adoc \ - cmds-purehelpers.adoc \ - cmds-foreignscminterface.adoc - -$(cmds_txt): cmd-list.made - -cmd-list.made: cmd-list.sh ../command-list.txt $(MAN1_TXT) - $(QUIET_GEN)$(SHELL_PATH) ./cmd-list.sh .. . $(cmds_txt) && \ - date >$@ - -mergetools-%.adoc: generate-mergetool-list.sh ../git-mergetool--lib.sh $(wildcard ../mergetools/*) -mergetools-diff.adoc: - $(QUIET_GEN)$(SHELL_PATH) ./generate-mergetool-list.sh .. diff $@ -mergetools-merge.adoc: - $(QUIET_GEN)$(SHELL_PATH) ./generate-mergetool-list.sh .. merge $@ - -TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK)) - -GIT-ASCIIDOCFLAGS: FORCE - @FLAGS='$(TRACK_ASCIIDOCFLAGS)'; \ - if test x"$$FLAGS" != x"`cat GIT-ASCIIDOCFLAGS 2>/dev/null`" ; then \ - echo >&2 " * new asciidoc flags"; \ - echo "$$FLAGS" >GIT-ASCIIDOCFLAGS; \ - fi - -clean: - $(RM) -rf .build/ - $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 - $(RM) *.texi *.texi+ *.texi++ git.info gitman.info - $(RM) *.pdf - $(RM) howto-index.adoc howto/*.html doc.dep - $(RM) technical/*.html technical/api-index.adoc - $(RM) SubmittingPatches.adoc - $(RM) $(cmds_txt) $(mergetools_txt) *.made - $(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 : %.adoc $(ASCIIDOC_DEPS) - $(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@ $< - -$(OBSOLETE_HTML): %.html : %.adoco $(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 : %.adoc $(ASCIIDOC_DEPS) - $(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $< - -user-manual.xml: user-manual.adoc $(ASCIIDOC_DEPS) - $(QUIET_ASCIIDOC)$(TXT_TO_XML) -d book -o $@ $< - -technical/api-index.adoc: technical/api-index-skel.adoc \ - technical/api-index.sh $(patsubst %,%.adoc,$(API_DOCS)) - $(QUIET_GEN)'$(SHELL_PATH_SQ)' technical/api-index.sh ./technical ./technical/api-index.adoc - -technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ -$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.adoc \ - $(ASCIIDOC_DEPS) - $(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.adoc - -SubmittingPatches.adoc: SubmittingPatches - $(QUIET_GEN) cp $< $@ - -XSLT = docbook.xsl -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)xsltproc $(XSLTOPTS) -o $@ $(XSLT) $< - -git.info: user-manual.texi - $(QUIET_MAKEINFO)$(MAKEINFO) --no-split -o $@ user-manual.texi - -user-manual.texi: user-manual.xml fix-texi.sh - $(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@+ && \ - $(SHELL_PATH) fix-texi.sh <$@+ >$@ && \ - $(RM) $@+ - -user-manual.pdf: user-manual.xml - $(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 $< - -$(patsubst %.adoc,%.texi,$(MAN_TXT)): %.texi : %.xml - $(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@ - -howto-index.adoc: howto/howto-index.sh $(HOWTO_TXT) - $(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto/howto-index.sh $(sort $(HOWTO_TXT)) >$@ - -$(patsubst %,%.html,$(ARTICLES)) : %.html : %.adoc $(ASCIIDOC_DEPS) - $(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.adoc - -WEBDOC_DEST = /pub/software/scm/git/docs - -howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ -$(patsubst %.adoc,%.html,$(HOWTO_TXT)): %.html : %.adoc $(ASCIIDOC_DEPS) - $(QUIET_ASCIIDOC) \ - sed -e '1,/^$$/d' $< | \ - $(TXT_TO_HTML) - >$@ - -install-webdoc : html - '$(SHELL_PATH_SQ)' ./install-webdoc.sh $(WEBDOC_DEST) - -# You must have a clone of 'git-htmldocs' and 'git-manpages' repositories -# next to the 'git' repository itself for the following to work. - -quick-install: quick-install-man - -require-manrepo:: - @if test ! -d $(MAN_REPO); \ - 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) $(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) $(GIT_MAN_REF) - -print-man1: - @for i in $(MAN1_TXT); do echo $$i; done - -## Lint: gitlink -LINT_DOCS_GITLINK = $(patsubst %.adoc,.build/lint-docs/gitlink/%.ok,$(HOWTO_TXT) $(DOC_DEP_TXT)) -$(LINT_DOCS_GITLINK): lint-gitlink.perl -$(LINT_DOCS_GITLINK): .build/lint-docs/gitlink/%.ok: %.adoc - $(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 %.adoc,.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: %.adoc - $(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 %.adoc,.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: %.adoc - $(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.adoc - $(call mkdir_p_parent_template) - $(QUIET_GEN)$(PERL_PATH) lint-fsck-msgids.perl \ - ../fsck.h fsck-msgids.adoc $@ -lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS) - -## Lint: delimited sections -LINT_DOCS_DELIMITED_SECTIONS = $(patsubst %.adoc,.build/lint-docs/delimited-sections/%.ok,$(MAN_TXT)) -$(LINT_DOCS_DELIMITED_SECTIONS): lint-delimited-sections.perl -$(LINT_DOCS_DELIMITED_SECTIONS): .build/lint-docs/delimited-sections/%.ok: %.adoc - $(call mkdir_p_parent_template) - $(QUIET_LINT_DELIMSEC)$(PERL_PATH) lint-delimited-sections.perl $< >$@ -.PHONY: lint-docs-delimited-sections -lint-docs-delimited-sections: $(LINT_DOCS_DELIMITED_SECTIONS) - -## Lint: Documentation style -LINT_DOCS_DOC_STYLE = $(patsubst %.adoc,.build/lint-docs/doc-style/%.ok,$(DOC_DEP_TXT)) -$(LINT_DOCS_DOC_STYLE): lint-documentation-style.perl -$(LINT_DOCS_DOC_STYLE): .build/lint-docs/doc-style/%.ok: %.adoc - $(call mkdir_p_parent_template) - $(QUIET_LINT_DOCSTYLE)$(PERL_PATH) lint-documentation-style.perl $< >$@ -.PHONY: lint-docs-doc-style -lint-docs-doc-style: $(LINT_DOCS_DOC_STYLE) - -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.adoc && \ - ls git*.adoc scalar.adoc | \ - grep -v -e git-bisect-lk2009.adoc \ - -e git-pack-redundant.adoc \ - -e git-tools.adoc \ - -e git-whatchanged.adoc \ - >tmp-meson-diff/actual.adoc && \ - if ! cmp tmp-meson-diff/meson.adoc tmp-meson-diff/actual.adoc; then \ - echo "Meson man pages differ from actual man pages:"; \ - diff -u tmp-meson-diff/meson.adoc tmp-meson-diff/actual.adoc; \ - 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-delimited-sections -lint-docs: lint-docs-doc-style -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.adoc b/Documentation/MyFirstContribution.adoc deleted file mode 100644 index b9fdefce0224c9..00000000000000 --- a/Documentation/MyFirstContribution.adoc +++ /dev/null @@ -1,1427 +0,0 @@ -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.adoc` - -[[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://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. - -==== https://discord.gg/GRFVkzgxRd[#discord] on Discord -This is an unofficial Git Discord server for everyone, from people just -starting out with Git to those who develop it. It's a great place to ask -questions, share tips, and connect with the broader Git community in real time. - -The server has channels for general discussions and specific channels for those -who use Git and those who develop it. The server's search functionality also -allows you to find previous conversations and answers to common questions. - -[[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 UNUSED, const char **argv UNUSED, - const char *prefix UNUSED, struct repository *repo UNUSED) ----- - -A few things to note: - -* A subcommand implementation takes its command line arguments - in `int argc` + `const char **argv`, like `main()` would. - -* It also takes two extra parameters, `prefix` and `repo`. What - they mean will not be discussed until much later. - -* Because this first example will not use any of the parameters, - your compiler will give warnings on unused parameters. As the - list of these four parameters is mandated by the API to add - new built-in commands, you cannot omit them. Instead, you add - `UNUSED` to each of them to tell the compiler that you *know* - you are not (yet) using it. - -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, struct repository *repo); ----- - -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 UNUSED, const char **argv UNUSED, - const char *prefix UNUSED, struct repository *repo UNUSED) -{ - 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; because the args are now -used, remove the `UNUSED` macro from them: - ----- - 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"`, `#include "repository.h"` and -`#include "environment.h"`. -Then, add the following bits to the function body: -function body: - ----- - const char *cfg_name; - -... - - repo_config(repo, git_default_config, NULL); - if (repo_config_get_string_tmp(repo, "user.name", &cfg_name)) - printf(_("No name is found in config\n")); - else - printf(_("Your name: %s\n"), cfg_name); ----- - -`repo_config()` will grab the configuration from config files known to Git and -apply standard precedence rules. `repo_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 `repo_config()`) in `config.h`. - -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 `repo_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(repo, &status); - repo_config(repo, 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" -#include "strbuf.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-*.adoc`. 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.adoc`. 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 --------- -[synopsis] -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.adoc`. 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. `-j$(nproc)` runs tests using all -available CPUs in parallel, but the job count can be adjusted as needed. -`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 either `gitgitgadget/git` or `git/git`. Head to -https://github.com/gitgitgadget/git or https://github.com/git/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. - -The differences between using `gitgitgadget/git` and `git/git` as your base can -be found [here](https://gitgitgadget.github.io/#should-i-use-gitgitgadget-on-gitgitgadgets-git-fork-or-on-gits-github-mirror) - -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.adoc | 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.adoc - 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. - -NOTE: After sending your patches, you can confirm that they reached the mailing -list by visiting https://lore.kernel.org/git/. Use the search bar to find your -name or the subject of your patch. If it appears, your email was successfully -delivered. - -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.adoc b/Documentation/MyFirstObjectWalk.adoc deleted file mode 100644 index 413a9fdb05c56e..00000000000000 --- a/Documentation/MyFirstObjectWalk.adoc +++ /dev/null @@ -1,913 +0,0 @@ -= 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.adoc` 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, struct repository *repo) -{ - 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_version()`: - ----- -int cmd_walken(int argc, const char **argv, const char *prefix, struct repository *repo); ----- - -Include the command in `git.c` in `commands[]` near the entry for `version`, -maintaining alphabetical ordering: - ----- -{ "walken", cmd_walken, RUN_SETUP }, ----- - -Add an entry for the new command in the both the Make and Meson build system, -before the entry for `worktree`: - -- In the `Makefile`: ----- -... -BUILTIN_OBJS += builtin/walken.o -... ----- - -- In the `meson.build` file: ----- -builtin_sources = [ - ... - 'builtin/walken.c', - ... -] ----- - -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.adoc`. - -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.adoc`.) - -`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.adoc` 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.adoc`. 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 `repo_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 `repo_config()` with it in your `cmd_walken()`: - ----- -int cmd_walken(int argc, const char **argv, const char *prefix, struct repository *repo) -{ - ... - - repo_config(repo, 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, struct repository *repo) -{ - /* This can go wherever you like in your declarations.*/ - struct rev_info rev; - ... - - /* This should go after the repo_config() call. */ - repo_init_revisions(repo, &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, struct repository *repo) -{ - ... - - 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.adoc`. 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.1.adoc b/Documentation/RelNotes/1.5.0.1.adoc deleted file mode 100644 index fea3f9935b7794..00000000000000 --- a/Documentation/RelNotes/1.5.0.1.adoc +++ /dev/null @@ -1,42 +0,0 @@ -GIT v1.5.0.1 Release Notes -========================== - -Fixes since v1.5.0 ------------------- - -* Documentation updates - - - Clarifications and corrections to 1.5.0 release notes. - - - The main documentation did not link to git-remote documentation. - - - Clarified introductory text of git-rebase documentation. - - - Converted remaining mentions of update-index on Porcelain - documents to git-add/git-rm. - - - Some i18n.* configuration variables were incorrectly - described as core.*; fixed. - -* Bugfixes - - - git-add and git-update-index on a filesystem on which - executable bits are unreliable incorrectly reused st_mode - bits even when the path changed between symlink and regular - file. - - - git-daemon marks the listening sockets with FD_CLOEXEC so - that it won't be leaked into the children. - - - segfault from git-blame when the mandatory pathname - parameter was missing was fixed; usage() message is given - instead. - - - git-rev-list did not read $GIT_DIR/config file, which means - that did not honor i18n.logoutputencoding correctly. - -* Tweaks - - - sliding mmap() inefficiently mmaped the same region of a - packfile with an access pattern that used objects in the - reverse order. This has been made more efficient. diff --git a/Documentation/RelNotes/1.5.0.2.adoc b/Documentation/RelNotes/1.5.0.2.adoc deleted file mode 100644 index b061e50ff05b5e..00000000000000 --- a/Documentation/RelNotes/1.5.0.2.adoc +++ /dev/null @@ -1,65 +0,0 @@ -GIT v1.5.0.2 Release Notes -========================== - -Fixes since v1.5.0.1 --------------------- - -* Bugfixes - - - Automated merge conflict handling when changes to symbolic - links conflicted were completely broken. The merge-resolve - strategy created a regular file with conflict markers in it - in place of the symbolic link. The default strategy, - merge-recursive was even more broken. It removed the path - that was pointed at by the symbolic link. Both of these - problems have been fixed. - - - 'git diff maint master next' did not correctly give combined - diff across three trees. - - - 'git fast-import' portability fix for Solaris. - - - 'git show-ref --verify' without arguments did not error out - but segfaulted. - - - 'git diff :tracked-file `pwd`/an-untracked-file' gave an extra - slashes after a/ and b/. - - - 'git format-patch' produced too long filenames if the commit - message had too long line at the beginning. - - - Running 'make all' and then without changing anything - running 'make install' still rebuilt some files. This - was inconvenient when building as yourself and then - installing as root (especially problematic when the source - directory is on NFS and root is mapped to nobody). - - - 'git-rerere' failed to deal with two unconflicted paths that - sorted next to each other. - - - 'git-rerere' attempted to open(2) a symlink and failed if - there was a conflict. Since a conflicting change to a - symlink would not benefit from rerere anyway, the command - now ignores conflicting changes to symlinks. - - - 'git-repack' did not like to pass more than 64 arguments - internally to underlying 'rev-list' logic, which made it - impossible to repack after accumulating many (small) packs - in the repository. - - - 'git-diff' to review the combined diff during a conflicted - merge were not reading the working tree version correctly - when changes to a symbolic link conflicted. It should have - read the data using readlink(2) but read from the regular - file the symbolic link pointed at. - - - 'git-remote' did not like period in a remote's name. - -* Documentation updates - - - added and clarified core.bare, core.legacyheaders configurations. - - - updated "git-clone --depth" documentation. - - -* Assorted git-gui fixes. diff --git a/Documentation/RelNotes/1.5.0.3.adoc b/Documentation/RelNotes/1.5.0.3.adoc deleted file mode 100644 index cd500f96bfd73e..00000000000000 --- a/Documentation/RelNotes/1.5.0.3.adoc +++ /dev/null @@ -1,58 +0,0 @@ -GIT v1.5.0.3 Release Notes -========================== - -Fixes since v1.5.0.2 --------------------- - -* Bugfixes - - - 'git.el' honors the commit coding system from the configuration. - - - 'blameview' in contrib/ correctly digs deeper when a line is - clicked. - - - 'http-push' correctly makes sure the remote side has leading - path. Earlier it started in the middle of the path, and - incorrectly. - - - 'git-merge' did not exit with non-zero status when the - working tree was dirty and cannot fast forward. It does - now. - - - 'cvsexportcommit' does not lose yet-to-be-used message file. - - - int-vs-size_t typefix when running combined diff on files - over 2GB long. - - - 'git apply --whitespace=strip' should not touch unmodified - lines. - - - 'git-mailinfo' choke when a logical header line was too long. - - - 'git show A..B' did not error out. Negative ref ("not A" in - this example) does not make sense for the purpose of the - command, so now it errors out. - - - 'git fmt-merge-msg --file' without file parameter did not - correctly error out. - - - 'git archimport' barfed upon encountering a commit without - summary. - - - 'git index-pack' did not protect itself from getting a short - read out of pread(2). - - - 'git http-push' had a few buffer overruns. - - - Build dependency fixes to rebuild fetch.o when other headers - change. - -* Documentation updates - - - user-manual updates. - - - Options to 'git remote add' were described insufficiently. - - - Configuration format.suffix was not documented. - - - Other formatting and spelling fixes. diff --git a/Documentation/RelNotes/1.5.0.4.adoc b/Documentation/RelNotes/1.5.0.4.adoc deleted file mode 100644 index feefa5dfd4eee5..00000000000000 --- a/Documentation/RelNotes/1.5.0.4.adoc +++ /dev/null @@ -1,22 +0,0 @@ -GIT v1.5.0.4 Release Notes -========================== - -Fixes since v1.5.0.3 --------------------- - -* Bugfixes - - - git.el does not add duplicate sign-off lines. - - - git-commit shows the full stat of the resulting commit, not - just about the files in the current directory, when run from - a subdirectory. - - - "git-checkout -m '@{8 hours ago}'" had a funny failure from - eval; fixed. - - - git-gui updates. - -* Documentation updates - -* User manual updates diff --git a/Documentation/RelNotes/1.5.0.5.adoc b/Documentation/RelNotes/1.5.0.5.adoc deleted file mode 100644 index eeec3d73d01a0e..00000000000000 --- a/Documentation/RelNotes/1.5.0.5.adoc +++ /dev/null @@ -1,26 +0,0 @@ -GIT v1.5.0.5 Release Notes -========================== - -Fixes since v1.5.0.3 --------------------- - -* Bugfixes - - - git-merge (hence git-pull) did not refuse fast-forwarding - when the working tree had local changes that would have - conflicted with it. - - - git.el does not add duplicate sign-off lines. - - - git-commit shows the full stat of the resulting commit, not - just about the files in the current directory, when run from - a subdirectory. - - - "git-checkout -m '@{8 hours ago}'" had a funny failure from - eval; fixed. - - - git-gui updates. - -* Documentation updates - -* User manual updates diff --git a/Documentation/RelNotes/1.5.0.6.adoc b/Documentation/RelNotes/1.5.0.6.adoc deleted file mode 100644 index c02015ad5fdb19..00000000000000 --- a/Documentation/RelNotes/1.5.0.6.adoc +++ /dev/null @@ -1,21 +0,0 @@ -GIT v1.5.0.6 Release Notes -========================== - -Fixes since v1.5.0.5 --------------------- - -* Bugfixes - - - a handful small fixes to gitweb. - - - build procedure for user-manual is fixed not to require locally - installed stylesheets. - - - "git commit $paths" on paths whose earlier contents were - already updated in the index were failing out. - -* Documentation - - - user-manual has better cross references. - - - gitweb installation/deployment procedure is now documented. diff --git a/Documentation/RelNotes/1.5.0.7.adoc b/Documentation/RelNotes/1.5.0.7.adoc deleted file mode 100644 index 670ad32b85678c..00000000000000 --- a/Documentation/RelNotes/1.5.0.7.adoc +++ /dev/null @@ -1,18 +0,0 @@ -GIT v1.5.0.7 Release Notes -========================== - -Fixes since v1.5.0.6 --------------------- - -* Bugfixes - - - git-upload-pack failed to close unused pipe ends, resulting - in many zombies to hang around. - - - git-rerere was recording the contents of earlier hunks - duplicated in later hunks. This prevented resolving the same - conflict when performing the same merge the other way around. - -* Documentation - - - a few documentation fixes from Debian package maintainer. diff --git a/Documentation/RelNotes/1.5.0.adoc b/Documentation/RelNotes/1.5.0.adoc deleted file mode 100644 index d6d42f31835889..00000000000000 --- a/Documentation/RelNotes/1.5.0.adoc +++ /dev/null @@ -1,469 +0,0 @@ -GIT v1.5.0 Release Notes -======================== - -Old news --------- - -This section is for people who are upgrading from ancient -versions of git. Although all of the changes in this section -happened before the current v1.4.4 release, they are summarized -here in the v1.5.0 release notes for people who skipped earlier -versions. - -As of git v1.5.0 there are some optional features that changes -the repository to allow data to be stored and transferred more -efficiently. These features are not enabled by default, as they -will make the repository unusable with older versions of git. -Specifically, the available options are: - - - There is a configuration variable core.legacyheaders that - changes the format of loose objects so that they are more - efficient to pack and to send out of the repository over git - native protocol, since v1.4.2. However, loose objects - written in the new format cannot be read by git older than - that version; people fetching from your repository using - older clients over dumb transports (e.g. http) using older - versions of git will also be affected. - - To let git use the new loose object format, you have to - set core.legacyheaders to false. - - - Since v1.4.3, configuration repack.usedeltabaseoffset allows - packfile to be created in more space efficient format, which - cannot be read by git older than that version. - - To let git use the new format for packfiles, you have to - set repack.usedeltabaseoffset to true. - -The above two new features are not enabled by default and you -have to explicitly ask for them, because they make repositories -unreadable by older versions of git, and in v1.5.0 we still do -not enable them by default for the same reason. We will change -this default probably 1 year after 1.4.2's release, when it is -reasonable to expect everybody to have new enough version of -git. - - - 'git pack-refs' appeared in v1.4.4; this command allows tags - to be accessed much more efficiently than the traditional - 'one-file-per-tag' format. Older git-native clients can - still fetch from a repository that packed and pruned refs - (the server side needs to run the up-to-date version of git), - but older dumb transports cannot. Packing of refs is done by - an explicit user action, either by use of "git pack-refs - --prune" command or by use of "git gc" command. - - - 'git -p' to paginate anything -- many commands do pagination - by default on a tty. Introduced between v1.4.1 and v1.4.2; - this may surprise old timers. - - - 'git archive' superseded 'git tar-tree' in v1.4.3; - - - 'git cvsserver' was new invention in v1.3.0; - - - 'git repo-config', 'git grep', 'git rebase' and 'gitk' were - seriously enhanced during v1.4.0 timeperiod. - - - 'gitweb' became part of git.git during v1.4.0 timeperiod and - seriously modified since then. - - - reflog is an v1.4.0 invention. This allows you to name a - revision that a branch used to be at (e.g. "git diff - master@{yesterday} master" allows you to see changes since - yesterday's tip of the branch). - - -Updates in v1.5.0 since v1.4.4 series -------------------------------------- - -* Index manipulation - - - git-add is to add contents to the index (aka "staging area" - for the next commit), whether the file the contents happen to - be is an existing one or a newly created one. - - - git-add without any argument does not add everything - anymore. Use 'git-add .' instead. Also you can add - otherwise ignored files with an -f option. - - - git-add tries to be more friendly to users by offering an - interactive mode ("git-add -i"). - - - git-commit used to refuse to commit if was - different between HEAD and the index (i.e. update-index was - used on it earlier). This check was removed. - - - git-rm is much saner and safer. It is used to remove paths - from both the index file and the working tree, and makes sure - you are not losing any local modification before doing so. - - - git-reset ... can be used to revert index - entries for selected paths. - - - git-update-index is much less visible. Many suggestions to - use the command in git output and documentation have now been - replaced by simpler commands such as "git add" or "git rm". - - -* Repository layout and objects transfer - - - The data for origin repository is stored in the configuration - file $GIT_DIR/config, not in $GIT_DIR/remotes/, for newly - created clones. The latter is still supported and there is - no need to convert your existing repository if you are - already comfortable with your workflow with the layout. - - - git-clone always uses what is known as "separate remote" - layout for a newly created repository with a working tree. - - A repository with the separate remote layout starts with only - one default branch, 'master', to be used for your own - development. Unlike the traditional layout that copied all - the upstream branches into your branch namespace (while - renaming their 'master' to your 'origin'), the new layout - puts upstream branches into local "remote-tracking branches" - with their own namespace. These can be referenced with names - such as "origin/$upstream_branch_name" and are stored in - .git/refs/remotes rather than .git/refs/heads where normal - branches are stored. - - This layout keeps your own branch namespace less cluttered, - avoids name collision with your upstream, makes it possible - to automatically track new branches created at the remote - after you clone from it, and makes it easier to interact with - more than one remote repository (you can use "git remote" to - add other repositories to track). There might be some - surprises: - - * 'git branch' does not show the remote tracking branches. - It only lists your own branches. Use '-r' option to view - the tracking branches. - - * If you are forking off of a branch obtained from the - upstream, you would have done something like 'git branch - my-next next', because traditional layout dropped the - tracking branch 'next' into your own branch namespace. - With the separate remote layout, you say 'git branch next - origin/next', which allows you to use the matching name - 'next' for your own branch. It also allows you to track a - remote other than 'origin' (i.e. where you initially cloned - from) and fork off of a branch from there the same way - (e.g. "git branch mingw j6t/master"). - - Repositories initialized with the traditional layout continue - to work. - - - New branches that appear on the origin side after a clone is - made are also tracked automatically. This is done with an - wildcard refspec "refs/heads/*:refs/remotes/origin/*", which - older git does not understand, so if you clone with 1.5.0, - you would need to downgrade remote.*.fetch in the - configuration file to specify each branch you are interested - in individually if you plan to fetch into the repository with - older versions of git (but why would you?). - - - Similarly, wildcard refspec "refs/heads/*:refs/remotes/me/*" - can be given to "git-push" command to update the tracking - branches that is used to track the repository you are pushing - from on the remote side. - - - git-branch and git-show-branch know remote tracking branches - (use the command line switch "-r" to list only tracked branches). - - - git-push can now be used to delete a remote branch or a tag. - This requires the updated git on the remote side (use "git - push :refs/heads/" to delete "branch"). - - - git-push more aggressively keeps the transferred objects - packed. Earlier we recommended to monitor amount of loose - objects and repack regularly, but you should repack when you - accumulated too many small packs this way as well. Updated - git-count-objects helps you with this. - - - git-fetch also more aggressively keeps the transferred objects - packed. This behavior of git-push and git-fetch can be - tweaked with a single configuration transfer.unpacklimit (but - usually there should not be any need for a user to tweak it). - - - A new command, git-remote, can help you manage your remote - tracking branch definitions. - - - You may need to specify explicit paths for upload-pack and/or - receive-pack due to your ssh daemon configuration on the - other end. This can now be done via remote.*.uploadpack and - remote.*.receivepack configuration. - - -* Bare repositories - - - Certain commands change their behavior in a bare repository - (i.e. a repository without associated working tree). We use - a fairly conservative heuristic (if $GIT_DIR is ".git", or - ends with "/.git", the repository is not bare) to decide if a - repository is bare, but "core.bare" configuration variable - can be used to override the heuristic when it misidentifies - your repository. - - - git-fetch used to complain updating the current branch but - this is now allowed for a bare repository. So is the use of - 'git-branch -f' to update the current branch. - - - Porcelain-ish commands that require a working tree refuses to - work in a bare repository. - - -* Reflog - - - Reflog records the history from the view point of the local - repository. In other words, regardless of the real history, - the reflog shows the history as seen by one particular - repository (this enables you to ask "what was the current - revision in _this_ repository, yesterday at 1pm?"). This - facility is enabled by default for repositories with working - trees, and can be accessed with the "branch@{time}" and - "branch@{Nth}" notation. - - - "git show-branch" learned showing the reflog data with the - new -g option. "git log" has -g option to view reflog - entries in a more verbose manner. - - - git-branch knows how to rename branches and moves existing - reflog data from the old branch to the new one. - - - In addition to the reflog support in v1.4.4 series, HEAD - reference maintains its own log. "HEAD@{5.minutes.ago}" - means the commit you were at 5 minutes ago, which takes - branch switching into account. If you want to know where the - tip of your current branch was at 5 minutes ago, you need to - explicitly say its name (e.g. "master@{5.minutes.ago}") or - omit the refname altogether i.e. "@{5.minutes.ago}". - - - The commits referred to by reflog entries are now protected - against pruning. The new command "git reflog expire" can be - used to truncate older reflog entries and entries that refer - to commits that have been pruned away previously with older - versions of git. - - Existing repositories that have been using reflog may get - complaints from fsck-objects and may not be able to run - git-repack, if you had run git-prune from older git; please - run "git reflog expire --stale-fix --all" first to remove - reflog entries that refer to commits that are no longer in - the repository when that happens. - - -* Cruft removal - - - We used to say "old commits are retrievable using reflog and - 'master@{yesterday}' syntax as long as you haven't run - git-prune". We no longer have to say the latter half of the - above sentence, as git-prune does not remove things reachable - from reflog entries. - - - There is a toplevel garbage collector script, 'git-gc', that - runs periodic cleanup functions, including 'git-repack -a -d', - 'git-reflog expire', 'git-pack-refs --prune', and 'git-rerere - gc'. - - - The output from fsck ("fsck-objects" is called just "fsck" - now, but the old name continues to work) was needlessly - alarming in that it warned missing objects that are reachable - only from dangling objects. This has been corrected and the - output is much more useful. - - -* Detached HEAD - - - You can use 'git-checkout' to check out an arbitrary revision - or a tag as well, instead of named branches. This will - dissociate your HEAD from the branch you are currently on. - - A typical use of this feature is to "look around". E.g. - - $ git checkout v2.6.16 - ... compile, test, etc. - $ git checkout v2.6.17 - ... compile, test, etc. - - - After detaching your HEAD, you can go back to an existing - branch with usual "git checkout $branch". Also you can - start a new branch using "git checkout -b $newbranch" to - start a new branch at that commit. - - - You can even pull from other repositories, make merges and - commits while your HEAD is detached. Also you can use "git - reset" to jump to arbitrary commit, while still keeping your - HEAD detached. - - Remember that a detached state is volatile, i.e. it will be forgotten - as soon as you move away from it with the checkout or reset command, - unless a branch is created from it as mentioned above. It is also - possible to rescue a lost detached state from the HEAD reflog. - - -* Packed refs - - - Repositories with hundreds of tags have been paying large - overhead, both in storage and in runtime, due to the - traditional one-ref-per-file format. A new command, - git-pack-refs, can be used to "pack" them in more efficient - representation (you can let git-gc do this for you). - - - Clones and fetches over dumb transports are now aware of - packed refs and can download from repositories that use - them. - - -* Configuration - - - configuration related to color setting are consolidated under - color.* namespace (older diff.color.*, status.color.* are - still supported). - - - 'git-repo-config' command is accessible as 'git-config' now. - - -* Updated features - - - git-describe uses better criteria to pick a base ref. It - used to pick the one with the newest timestamp, but now it - picks the one that is topologically the closest (that is, - among ancestors of commit C, the ref T that has the shortest - output from "git-rev-list T..C" is chosen). - - - git-describe gives the number of commits since the base ref - between the refname and the hash suffix. E.g. the commit one - before v2.6.20-rc6 in the kernel repository is: - - v2.6.20-rc5-306-ga21b069 - - which tells you that its object name begins with a21b069, - v2.6.20-rc5 is an ancestor of it (meaning, the commit - contains everything -rc5 has), and there are 306 commits - since v2.6.20-rc5. - - - git-describe with --abbrev=0 can be used to show only the - name of the base ref. - - - git-blame learned a new option, --incremental, that tells it - to output the blames as they are assigned. A sample script - to use it is also included as contrib/blameview. - - - git-blame starts annotating from the working tree by default. - - -* Less external dependency - - - We no longer require the "merge" program from the RCS suite. - All 3-way file-level merges are now done internally. - - - The original implementation of git-merge-recursive which was - in Python has been removed; we have a C implementation of it - now. - - - git-shortlog is no longer a Perl script. It no longer - requires output piped from git-log; it can accept revision - parameters directly on the command line. - - -* I18n - - - We have always encouraged the commit message to be encoded in - UTF-8, but the users are allowed to use legacy encoding as - appropriate for their projects. This will continue to be the - case. However, a non UTF-8 commit encoding _must_ be - explicitly set with i18n.commitencoding in the repository - where a commit is made; otherwise git-commit-tree will - complain if the log message does not look like a valid UTF-8 - string. - - - 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 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 - configuration, in the decreasing order of preference, and - defaults to UTF-8. - - - Tools for e-mailed patch application now default to -u - behavior; i.e. it always re-codes from the e-mailed encoding - to the encoding specified with i18n.commitencoding. This - unfortunately forces projects that have happily been using a - legacy encoding without setting i18n.commitencoding to set - the configuration, but taken with other improvement, please - excuse us for this very minor one-time inconvenience. - - -* e-mailed patches - - - See the above I18n section. - - - git-format-patch now enables --binary without being asked. - git-am does _not_ default to it, as sending binary patch via - e-mail is unusual and is harder to review than textual - patches and it is prudent to require the person who is - applying the patch to explicitly ask for it. - - - The default suffix for git-format-patch output is now ".patch", - not ".txt". This can be changed with --suffix=.txt option, - or setting the config variable "format.suffix" to ".txt". - - -* Foreign SCM interfaces - - - git-svn now requires the Perl SVN:: libraries, the - command-line backend was too slow and limited. - - - the 'commit' subcommand of git-svn has been renamed to - 'set-tree', and 'dcommit' is the recommended replacement for - day-to-day work. - - - git fast-import backend. - - -* User support - - - Quite a lot of documentation updates. - - - Bash completion scripts have been updated heavily. - - - Better error messages for often used Porcelainish commands. - - - Git GUI. This is a simple Tk based graphical interface for - common Git operations. - - -* Sliding mmap - - - We used to assume that we can mmap the whole packfile while - in use, but with a large project this consumes huge virtual - memory space and truly huge ones would not fit in the - userland address space on 32-bit platforms. We now mmap huge - packfile in pieces to avoid this problem. - - -* Shallow clones - - - There is a partial support for 'shallow' repositories that - keeps only recent history. A 'shallow clone' is created by - specifying how deep that truncated history should be - (e.g. "git clone --depth 5 git://some.where/repo.git"). - - Currently a shallow repository has number of limitations: - - - Cloning and fetching _from_ a shallow clone are not - supported (nor tested -- so they might work by accident but - they are not expected to). - - - Pushing from nor into a shallow clone are not expected to - work. - - - Merging inside a shallow repository would work as long as a - merge base is found in the recent history, but otherwise it - will be like merging unrelated histories and may result in - huge conflicts. - - but this would be more than adequate for people who want to - look at near the tip of a big project with a deep history and - send patches in e-mail format. diff --git a/Documentation/RelNotes/1.5.1.1.adoc b/Documentation/RelNotes/1.5.1.1.adoc deleted file mode 100644 index 91471213bdec8d..00000000000000 --- a/Documentation/RelNotes/1.5.1.1.adoc +++ /dev/null @@ -1,65 +0,0 @@ -GIT v1.5.1.1 Release Notes -========================== - -Fixes since v1.5.1 ------------------- - -* Documentation updates - - - The --left-right option of rev-list and friends is documented. - - - The documentation for cvsimport has been majorly improved. - - - "git-show-ref --exclude-existing" was documented. - -* Bugfixes - - - The implementation of -p option in "git cvsexportcommit" had - the meaning of -C (context reduction) option wrong, and - loosened the context requirements when it was told to be - strict. - - - "git cvsserver" did not behave like the real cvsserver when - client side removed a file from the working tree without - doing anything else on the path. In such a case, it should - restore it from the checked out revision. - - - "git fsck" issued an alarming error message on detached - HEAD. It is not an error since at least 1.5.0. - - - "git send-email" produced of References header of unbounded length; - fixed this with line-folding. - - - "git archive" to download from remote site should not - require you to be in a git repository, but it incorrectly - did. - - - "git apply" ignored -p for "diff --git" formatted - patches. - - - "git rerere" recorded a conflict that had one side empty - (the other side adds) incorrectly; this made merging in the - other direction fail to use previously recorded resolution. - - - t4200 test was broken where "wc -l" pads its output with - spaces. - - - "git branch -m old new" to rename branch did not work - without a configuration file in ".git/config". - - - The sample hook for notification e-mail was misnamed. - - - gitweb did not show type-changing patch correctly in the - blobdiff view. - - - git-svn did not error out with incorrect command line options. - - - git-svn fell into an infinite loop when insanely long commit - message was found. - - - git-svn dcommit and rebase was confused by patches that were - merged from another branch that is managed by git-svn. - - - git-svn used to get confused when globbing remote branch/tag - spec (e.g. "branches = proj/branches/*:refs/remotes/origin/*") - is used and there was a plain file that matched the glob. diff --git a/Documentation/RelNotes/1.5.1.2.adoc b/Documentation/RelNotes/1.5.1.2.adoc deleted file mode 100644 index d88456306c503d..00000000000000 --- a/Documentation/RelNotes/1.5.1.2.adoc +++ /dev/null @@ -1,50 +0,0 @@ -GIT v1.5.1.2 Release Notes -========================== - -Fixes since v1.5.1.1 --------------------- - -* Bugfixes - - - "git clone" over http from a repository that has lost the - loose refs by running "git pack-refs" were broken (a code to - deal with this was added to "git fetch" in v1.5.0, but it - was missing from "git clone"). - - - "git diff a/ b/" incorrectly fell in "diff between two - filesystem objects" codepath, when the user most likely - wanted to limit the extent of output to two tracked - directories. - - - git-quiltimport had the same bug as we fixed for - git-applymbox in v1.5.1.1 -- it gave an alarming "did not - have any patch" message (but did not actually fail and was - harmless). - - - various git-svn fixes. - - - Sample update hook incorrectly always refused requests to - delete branches through push. - - - git-blame on a very long working tree path had buffer - overrun problem. - - - git-apply did not like to be fed two patches in a row that created - and then modified the same file. - - - git-svn was confused when a non-project was stored directly under - trunk/, branches/ and tags/. - - - git-svn wants the Error.pm module that was at least as new - as what we ship as part of git; install ours in our private - installation location if the one on the system is older. - - - An earlier update to command line integer parameter parser was - botched and made 'update-index --cacheinfo' completely useless. - - -* Documentation updates - - - Various documentation updates from J. Bruce Fields, Frank - Lichtenheld, Alex Riesen and others. Andrew Ruder started a - war on undocumented options. diff --git a/Documentation/RelNotes/1.5.1.3.adoc b/Documentation/RelNotes/1.5.1.3.adoc deleted file mode 100644 index 876408b65a0e08..00000000000000 --- a/Documentation/RelNotes/1.5.1.3.adoc +++ /dev/null @@ -1,45 +0,0 @@ -GIT v1.5.1.3 Release Notes -========================== - -Fixes since v1.5.1.2 --------------------- - -* Bugfixes - - - git-add tried to optimize by finding common leading - directories across its arguments but botched, causing very - confused behaviour. - - - unofficial rpm.spec file shipped with git was letting - ETC_GITCONFIG set to /usr/etc/gitconfig. Tweak the official - Makefile to make it harder for distro people to make the - same mistake, by setting the variable to /etc/gitconfig if - prefix is set to /usr. - - - git-svn inconsistently stripped away username from the URL - only when svnsync_props was in use. - - - git-svn got confused when handling symlinks on Mac OS. - - - git-send-email was not quoting recipient names that have - period '.' in them. Also it did not allow overriding - envelope sender, which made it impossible to send patches to - certain subscriber-only lists. - - - built-in write_tree() routine had a sequence that renamed a - file that is still open, which some systems did not like. - - - when memory is very tight, sliding mmap code to read - packfiles incorrectly closed the fd that was still being - used to read the pack. - - - import-tars contributed front-end for fastimport was passing - wrong directory modes without checking. - - - git-fastimport trusted its input too much and allowed to - create corrupt tree objects with entries without a name. - - - git-fetch needlessly barfed when too long reflog action - description was given by the caller. - -Also contains various documentation updates. diff --git a/Documentation/RelNotes/1.5.1.4.adoc b/Documentation/RelNotes/1.5.1.4.adoc deleted file mode 100644 index df2f66ccb5d2a6..00000000000000 --- a/Documentation/RelNotes/1.5.1.4.adoc +++ /dev/null @@ -1,30 +0,0 @@ -GIT v1.5.1.4 Release Notes -========================== - -Fixes since v1.5.1.3 --------------------- - -* Bugfixes - - - "git-http-fetch" did not work around a bug in libcurl - earlier than 7.16 (curl_multi_remove_handle() was broken). - - - "git cvsserver" handles a file that was once removed and - then added again correctly. - - - import-tars script (in contrib/) handles GNU tar archives - that contain pathnames longer than 100 bytes (long-link - extension) correctly. - - - xdelta test program did not build correctly. - - - gitweb sometimes tried incorrectly to apply function to - decode utf8 twice, resulting in corrupt output. - - - "git blame -C" mishandled text at the end of a group of - lines. - - - "git log/rev-list --boundary" did not produce output - correctly without --left-right option. - - - Many documentation updates. diff --git a/Documentation/RelNotes/1.5.1.5.adoc b/Documentation/RelNotes/1.5.1.5.adoc deleted file mode 100644 index b0ab8eb371ccb0..00000000000000 --- a/Documentation/RelNotes/1.5.1.5.adoc +++ /dev/null @@ -1,42 +0,0 @@ -GIT v1.5.1.5 Release Notes -========================== - -Fixes since v1.5.1.4 --------------------- - -* Bugfixes - - - git-send-email did not understand aliases file for mutt, which - allows leading whitespaces. - - - git-format-patch emitted Content-Type and Content-Transfer-Encoding - headers for non ASCII contents, but failed to add MIME-Version. - - - git-name-rev had a buffer overrun with a deep history. - - - contributed script import-tars did not get the directory in - tar archives interpreted correctly. - - - git-svn was reported to segfault for many people on list and - #git; hopefully this has been fixed. - - - "git-svn clone" does not try to minimize the URL - (i.e. connect to higher level hierarchy) by default, as this - can prevent clone to fail if only part of the repository - (e.g. 'trunk') is open to public. - - - "git checkout branch^0" did not detach the head when you are - already on 'branch'; backported the fix from the 'master'. - - - "git-config section.var" did not correctly work when - existing configuration file had both [section] and [section "name"] - next to each other. - - - "git clone ../other-directory" was fooled if the current - directory $PWD points at is a symbolic link. - - - (build) tree_entry_extract() function was both static inline - and extern, which caused trouble compiling with Forte12 - compilers on Sun. - - - Many many documentation fixes and updates. diff --git a/Documentation/RelNotes/1.5.1.6.adoc b/Documentation/RelNotes/1.5.1.6.adoc deleted file mode 100644 index 55f3ac13e3c242..00000000000000 --- a/Documentation/RelNotes/1.5.1.6.adoc +++ /dev/null @@ -1,45 +0,0 @@ -GIT v1.5.1.6 Release Notes -========================== - -Fixes since v1.5.1.4 --------------------- - -* Bugfixes - - - git-send-email did not understand aliases file for mutt, which - allows leading whitespaces. - - - git-format-patch emitted Content-Type and Content-Transfer-Encoding - headers for non ASCII contents, but failed to add MIME-Version. - - - git-name-rev had a buffer overrun with a deep history. - - - contributed script import-tars did not get the directory in - tar archives interpreted correctly. - - - git-svn was reported to segfault for many people on list and - #git; hopefully this has been fixed. - - - git-svn also had a bug to crash svnserve by sending a bad - sequence of requests. - - - "git-svn clone" does not try to minimize the URL - (i.e. connect to higher level hierarchy) by default, as this - can prevent clone to fail if only part of the repository - (e.g. 'trunk') is open to public. - - - "git checkout branch^0" did not detach the head when you are - already on 'branch'; backported the fix from the 'master'. - - - "git-config section.var" did not correctly work when - existing configuration file had both [section] and [section "name"] - next to each other. - - - "git clone ../other-directory" was fooled if the current - directory $PWD points at is a symbolic link. - - - (build) tree_entry_extract() function was both static inline - and extern, which caused trouble compiling with Forte12 - compilers on Sun. - - - Many many documentation fixes and updates. diff --git a/Documentation/RelNotes/1.5.1.adoc b/Documentation/RelNotes/1.5.1.adoc deleted file mode 100644 index daed3672709f6b..00000000000000 --- a/Documentation/RelNotes/1.5.1.adoc +++ /dev/null @@ -1,371 +0,0 @@ -GIT v1.5.1 Release Notes -======================== - -Updates since v1.5.0 --------------------- - -* Deprecated commands and options. - - - git-diff-stages and git-resolve have been removed. - -* New commands and options. - - - "git log" and friends take --reverse, which instructs them - to give their output in the order opposite from their usual. - They typically output from new to old, but with this option - their output would read from old to new. "git shortlog" - usually lists older commits first, but with this option, - they are shown from new to old. - - - "git log --pretty=format:" to allow more flexible - custom log output. - - - "git diff" learned --ignore-space-at-eol. This is a weaker - form of --ignore-space-change. - - - "git diff --no-index pathA pathB" can be used as diff - replacement with git specific enhancements. - - - "git diff --no-index" can read from '-' (standard input). - - - "git diff" also learned --exit-code to exit with non-zero - status when it found differences. In the future we might - want to make this the default but that would be a rather big - backward incompatible change; it will stay as an option for - now. - - - "git diff --quiet" is --exit-code with output turned off, - meant for scripted use to quickly determine if there is any - tree-level difference. - - - Textual patch generation with "git diff" without -w/-b - option has been significantly optimized. "git blame" got - faster because of the same change. - - - "git log" and "git rev-list" has been optimized - significantly when they are used with pathspecs. - - - "git branch --track" can be used to set up configuration - variables to help it easier to base your work on branches - you track from a remote site. - - - "git format-patch --attach" now emits attachments. Use - --inline to get an inlined multipart/mixed. - - - "git name-rev" learned --refs=, to limit the tags - used for naming the given revisions only to the ones - matching the given pattern. - - - "git remote update" is to run "git fetch" for defined remotes - to update tracking branches. - - - "git cvsimport" can now take '-d' to talk with a CVS - repository different from what are recorded in CVS/Root - (overriding it with environment CVSROOT does not work). - - - "git bundle" can help sneaker-netting your changes between - repositories. - - - "git mergetool" can help 3-way file-level conflict - resolution with your favorite graphical merge tools. - - - A new configuration "core.symlinks" can be used to disable - symlinks on filesystems that do not support them; they are - checked out as regular files instead. - - - You can name a commit object with its first line of the - message. The syntax to use is ':/message text'. E.g. - - $ git show ":/object name: introduce ':/' notation" - - means the same thing as: - - $ git show 28a4d940443806412effa246ecc7768a21553ec7 - - - "git bisect" learned a new command "run" that takes a script - to run after each revision is checked out to determine if it - is good or bad, to automate the bisection process. - - - "git log" family learned a new traversal option --first-parent, - which does what the name suggests. - - -* Updated behavior of existing commands. - - - "git-merge-recursive" used to barf when there are more than - one common ancestors for the merge, and merging them had a - rename/rename conflict. This has been fixed. - - - "git fsck" does not barf on corrupt loose objects. - - - "git rm" does not remove newly added files without -f. - - - "git archimport" allows remapping when coming up with git - branch names from arch names. - - - git-svn got almost a rewrite. - - - core.autocrlf configuration, when set to 'true', makes git - to convert CRLF at the end of lines in text files to LF when - reading from the filesystem, and convert in reverse when - writing to the filesystem. The variable can be set to - 'input', in which case the conversion happens only while - reading from the filesystem but files are written out with - LF at the end of lines. Currently, which paths to consider - 'text' (i.e. be subjected to the autocrlf mechanism) is - decided purely based on the contents, but the plan is to - allow users to explicitly override this heuristic based on - paths. - - - The behavior of 'git-apply', when run in a subdirectory, - without --index nor --cached were inconsistent with that of - the command with these options. This was fixed to match the - behavior with --index. A patch that is meant to be applied - with -p1 from the toplevel of the project tree can be - applied with any custom -p option. A patch that is not - relative to the toplevel needs to be applied with -p - option with or without --index (or --cached). - - - "git diff" outputs a trailing HT when pathnames have embedded - SP on +++/--- header lines, in order to help "GNU patch" to - parse its output. "git apply" was already updated to accept - this modified output format since ce74618d (Sep 22, 2006). - - - "git cvsserver" runs hooks/update and honors its exit status. - - - "git cvsserver" can be told to send everything with -kb. - - - "git diff --check" also honors the --color output option. - - - "git name-rev" used to stress the fact that a ref is a tag too - much, by saying something like "v1.2.3^0~22". It now says - "v1.2.3~22" in such a case (it still says "v1.2.3^0" if it does - not talk about an ancestor of the commit that is tagged, which - makes sense). - - - "git rev-list --boundary" now shows boundary markers for the - commits omitted by --max-age and --max-count condition. - - - The configuration mechanism now reads $(prefix)/etc/gitconfig. - - - "git apply --verbose" shows what preimage lines were wanted - when it couldn't find them. - - - "git status" in a read-only repository got a bit saner. - - - "git fetch" (hence "git clone" and "git pull") are less - noisy when the output does not go to tty. - - - "git fetch" between repositories with many refs were slow - even when there are not many changes that needed - transferring. This has been sped up by partially rewriting - the heaviest parts in C. - - - "git mailinfo" which splits an e-mail into a patch and the - meta-information was rewritten, thanks to Don Zickus. It - handles nested multipart better. The command was broken for - a brief period on 'master' branch since 1.5.0 but the - breakage is fixed now. - - - send-email learned configurable bcc and chain-reply-to. - - - "git remote show $remote" also talks about branches that - would be pushed if you run "git push remote". - - - Using objects from packs is now seriously optimized by clever - use of a cache. This should be most noticeable in git-log - family of commands that involve reading many tree objects. - In addition, traversing revisions while filtering changes - with pathspecs is made faster by terminating the comparison - between the trees as early as possible. - - -* Hooks - - - The part to send out notification e-mails was removed from - the sample update hook, as it was not an appropriate place - to do so. The proper place to do this is the new post-receive - hook. An example hook has been added to contrib/hooks/. - - -* Others - - - git-revert, git-gc and git-cherry-pick are now built-ins. - -Fixes since v1.5.0 ------------------- - -These are all in v1.5.0.x series. - -* Documentation updates - - - Clarifications and corrections to 1.5.0 release notes. - - - The main documentation did not link to git-remote documentation. - - - Clarified introductory text of git-rebase documentation. - - - Converted remaining mentions of update-index on Porcelain - documents to git-add/git-rm. - - - Some i18n.* configuration variables were incorrectly - described as core.*; fixed. - - - added and clarified core.bare, core.legacyheaders configurations. - - - updated "git-clone --depth" documentation. - - - user-manual updates. - - - Options to 'git remote add' were described insufficiently. - - - Configuration format.suffix was not documented. - - - Other formatting and spelling fixes. - - - user-manual has better cross references. - - - gitweb installation/deployment procedure is now documented. - - -* Bugfixes - - - git-upload-pack closes unused pipe ends; earlier this caused - many zombies to hang around. - - - git-rerere was recording the contents of earlier hunks - duplicated in later hunks. This prevented resolving the same - conflict when performing the same merge the other way around. - - - git-add and git-update-index on a filesystem on which - executable bits are unreliable incorrectly reused st_mode - bits even when the path changed between symlink and regular - file. - - - git-daemon marks the listening sockets with FD_CLOEXEC so - that it won't be leaked into the children. - - - segfault from git-blame when the mandatory pathname - parameter was missing was fixed; usage() message is given - instead. - - - git-rev-list did not read $GIT_DIR/config file, which means - that did not honor i18n.logoutputencoding correctly. - - - Automated merge conflict handling when changes to symbolic - links conflicted were completely broken. The merge-resolve - strategy created a regular file with conflict markers in it - in place of the symbolic link. The default strategy, - merge-recursive was even more broken. It removed the path - that was pointed at by the symbolic link. Both of these - problems have been fixed. - - - 'git diff maint master next' did not correctly give combined - diff across three trees. - - - 'git fast-import' portability fix for Solaris. - - - 'git show-ref --verify' without arguments did not error out - but segfaulted. - - - 'git diff :tracked-file `pwd`/an-untracked-file' gave an extra - slashes after a/ and b/. - - - 'git format-patch' produced too long filenames if the commit - message had too long line at the beginning. - - - Running 'make all' and then without changing anything - running 'make install' still rebuilt some files. This - was inconvenient when building as yourself and then - installing as root (especially problematic when the source - directory is on NFS and root is mapped to nobody). - - - 'git-rerere' failed to deal with two unconflicted paths that - sorted next to each other. - - - 'git-rerere' attempted to open(2) a symlink and failed if - there was a conflict. Since a conflicting change to a - symlink would not benefit from rerere anyway, the command - now ignores conflicting changes to symlinks. - - - 'git-repack' did not like to pass more than 64 arguments - internally to underlying 'rev-list' logic, which made it - impossible to repack after accumulating many (small) packs - in the repository. - - - 'git-diff' to review the combined diff during a conflicted - merge were not reading the working tree version correctly - when changes to a symbolic link conflicted. It should have - read the data using readlink(2) but read from the regular - file the symbolic link pointed at. - - - 'git-remote' did not like period in a remote's name. - - - 'git.el' honors the commit coding system from the configuration. - - - 'blameview' in contrib/ correctly digs deeper when a line is - clicked. - - - 'http-push' correctly makes sure the remote side has leading - path. Earlier it started in the middle of the path, and - incorrectly. - - - 'git-merge' did not exit with non-zero status when the - working tree was dirty and cannot fast forward. It does - now. - - - 'cvsexportcommit' does not lose yet-to-be-used message file. - - - int-vs-size_t typefix when running combined diff on files - over 2GB long. - - - 'git apply --whitespace=strip' should not touch unmodified - lines. - - - 'git-mailinfo' choke when a logical header line was too long. - - - 'git show A..B' did not error out. Negative ref ("not A" in - this example) does not make sense for the purpose of the - command, so now it errors out. - - - 'git fmt-merge-msg --file' without file parameter did not - correctly error out. - - - 'git archimport' barfed upon encountering a commit without - summary. - - - 'git index-pack' did not protect itself from getting a short - read out of pread(2). - - - 'git http-push' had a few buffer overruns. - - - Build dependency fixes to rebuild fetch.o when other headers - change. - - - git.el does not add duplicate sign-off lines. - - - git-commit shows the full stat of the resulting commit, not - just about the files in the current directory, when run from - a subdirectory. - - - "git-checkout -m '@{8 hours ago}'" had a funny failure from - eval; fixed. - - - git-merge (hence git-pull) did not refuse fast-forwarding - when the working tree had local changes that would have - conflicted with it. - - - a handful small fixes to gitweb. - - - build procedure for user-manual is fixed not to require locally - installed stylesheets. - - - "git commit $paths" on paths whose earlier contents were - already updated in the index were failing out. - - -* Tweaks - - - sliding mmap() inefficiently mmaped the same region of a - packfile with an access pattern that used objects in the - reverse order. This has been made more efficient. diff --git a/Documentation/RelNotes/1.5.2.1.adoc b/Documentation/RelNotes/1.5.2.1.adoc deleted file mode 100644 index d41984df0b6b78..00000000000000 --- a/Documentation/RelNotes/1.5.2.1.adoc +++ /dev/null @@ -1,47 +0,0 @@ -GIT v1.5.2.1 Release Notes -========================== - -Fixes since v1.5.2 ------------------- - -* Bugfixes - - - Temporary files that are used when invoking external diff - programs did not tolerate a long TMPDIR. - - - git-daemon did not notice when it could not write into its - pid file. - - - git-status did not honor core.excludesFile configuration like - git-add did. - - - git-annotate did not work from a subdirectory while - git-blame did. - - - git-cvsserver should have disabled access to a repository - with "gitcvs.pserver.enabled = false" set even when - "gitcvs.enabled = true" was set at the same time. It - didn't. - - - git-cvsimport did not work correctly in a repository with - its branch heads were packed with pack-refs. - - - ident unexpansion to squash "$Id: xxx $" that is in the - repository copy removed incorrect number of bytes. - - - git-svn misbehaved when the subversion repository did not - provide MD5 checksums for files. - - - git rebase (and git am) misbehaved on commits that have '\n' - (literally backslash and en, not a linefeed) in the title. - - - code to decode base85 used in binary patches had one error - return codepath wrong. - - - RFC2047 Q encoding output by git-format-patch used '_' for a - space, which is not understood by some programs. It uses =20 - which is safer. - - - git-fastimport --import-marks was broken; fixed. - - - A lot of documentation updates, clarifications and fixes. diff --git a/Documentation/RelNotes/1.5.2.2.adoc b/Documentation/RelNotes/1.5.2.2.adoc deleted file mode 100644 index 7bfa3417506066..00000000000000 --- a/Documentation/RelNotes/1.5.2.2.adoc +++ /dev/null @@ -1,61 +0,0 @@ -GIT v1.5.2.2 Release Notes -========================== - -Fixes since v1.5.2.1 --------------------- - -* Usability fix - - - git-gui is shipped with its updated blame interface. It is - rumored that the older one was not just unusable but was - active health hazard, but this one is actually pretty. - Please see for yourself. - -* Bugfixes - - - "git checkout fubar" was utterly confused when there is a - branch fubar and a tag fubar at the same time. It correctly - checks out the branch fubar now. - - - "git clone /path/foo" to clone a local /path/foo.git - repository left an incorrect configuration. - - - "git send-email" correctly unquotes RFC 2047 quoted names in - the patch-email before using their values. - - - We did not accept number of seconds since epoch older than - year 2000 as a valid timestamp. We now interpret positive - integers more than 8 digits as such, which allows us to - express timestamps more recent than March 1973. - - - git-cvsimport did not work when you have GIT_DIR to point - your repository at a nonstandard location. - - - Some systems (notably, Solaris) lack hstrerror() to make - h_errno human readable; prepare a replacement - implementation. - - - .gitignore file listed git-core.spec but what we generate is - git.spec, and nobody noticed for a long time. - - - "git-merge-recursive" does not try to run file level merge - on binary files. - - - "git-branch --track" did not create tracking configuration - correctly when the branch name had slash in it. - - - The email address of the user specified with user.email - configuration was overridden by EMAIL environment variable. - - - The tree parser did not warn about tree entries with - nonsense file modes, and assumed they must be blobs. - - - "git log -z" without any other request to generate diff still - invoked the diff machinery, wasting cycles. - -* Documentation - - - Many updates to fix stale or missing documentation. - - - Although our documentation was primarily meant to be formatted - with AsciiDoc7, formatting with AsciiDoc8 is supported better. diff --git a/Documentation/RelNotes/1.5.2.3.adoc b/Documentation/RelNotes/1.5.2.3.adoc deleted file mode 100644 index addb22955b4e4e..00000000000000 --- a/Documentation/RelNotes/1.5.2.3.adoc +++ /dev/null @@ -1,27 +0,0 @@ -GIT v1.5.2.3 Release Notes -========================== - -Fixes since v1.5.2.2 --------------------- - - * Bugfixes - - - Version 2 pack index format was introduced in version 1.5.2 - to support pack files that has offset that cannot be - represented in 32-bit. The runtime code to validate such - an index mishandled such an index for an empty pack. - - - Commit walkers (most notably, fetch over http protocol) - tried to traverse commit objects contained in trees (aka - subproject); they shouldn't. - - - A build option NO_R_TO_GCC_LINKER was not explained in Makefile - comment correctly. - - * Documentation Fixes and Updates - - - git-config --regexp was not documented properly. - - - git-repack -a was not documented properly. - - - git-remote -n was not documented properly. diff --git a/Documentation/RelNotes/1.5.2.4.adoc b/Documentation/RelNotes/1.5.2.4.adoc deleted file mode 100644 index 75cff475f65464..00000000000000 --- a/Documentation/RelNotes/1.5.2.4.adoc +++ /dev/null @@ -1,28 +0,0 @@ -GIT v1.5.2.4 Release Notes -========================== - -Fixes since v1.5.2.3 --------------------- - - * Bugfixes - - - "git-gui" bugfixes, including a handful fixes to run it - better on Cygwin/MSYS. - - - "git checkout" failed to switch back and forth between - branches, one of which has "frotz -> xyzzy" symlink and - file "xyzzy/filfre", while the other one has a file - "frotz/filfre". - - - "git prune" used to segfault upon seeing a commit that is - referred to by a tree object (aka "subproject"). - - - "git diff --name-status --no-index" mishandled an added file. - - - "git apply --reverse --whitespace=warn" still complained - about whitespaces that a forward application would have - introduced. - - * Documentation Fixes and Updates - - - A handful documentation updates. diff --git a/Documentation/RelNotes/1.5.2.5.adoc b/Documentation/RelNotes/1.5.2.5.adoc deleted file mode 100644 index e8281c72a0b997..00000000000000 --- a/Documentation/RelNotes/1.5.2.5.adoc +++ /dev/null @@ -1,30 +0,0 @@ -GIT v1.5.2.5 Release Notes -========================== - -Fixes since v1.5.2.4 --------------------- - - * Bugfixes - - - "git add -u" had a serious data corruption problem in one - special case (when the changes to a subdirectory's files - consist only deletion of files). - - - "git add -u " did not work from a subdirectory. - - - "git apply" left an empty directory after all its files are - renamed away. - - - "git $anycmd foo/bar", when there is a file 'foo' in the - working tree, complained that "git $anycmd foo/bar --" form - should be used to disambiguate between revs and files, - which was completely bogus. - - - "git checkout-index" and other commands that checks out - files to the work tree tried unlink(2) on directories, - which is a sane thing to do on sane systems, but not on - Solaris when you are root. - - * Documentation Fixes and Updates - - - A handful documentation fixes. diff --git a/Documentation/RelNotes/1.5.2.adoc b/Documentation/RelNotes/1.5.2.adoc deleted file mode 100644 index e8328d090a438e..00000000000000 --- a/Documentation/RelNotes/1.5.2.adoc +++ /dev/null @@ -1,197 +0,0 @@ -GIT v1.5.2 Release Notes -======================== - -Updates since v1.5.1 --------------------- - -* Plumbing level superproject support. - - You can include a subdirectory that has an independent git - repository in your index and tree objects of your project - ("superproject"). This plumbing (i.e. "core") level - superproject support explicitly excludes recursive behaviour. - - The "subproject" entries in the index and trees of a superproject - are incompatible with older versions of git. Experimenting with - the plumbing level support is encouraged, but be warned that - unless everybody in your project updates to this release or - later, using this feature would make your project - inaccessible by people with older versions of git. - -* Plumbing level gitattributes support. - - The gitattributes mechanism allows you to add 'attributes' to - paths in your project, and affect the way certain git - operations work. Currently you can influence if a path is - considered a binary or text (the former would be treated by - 'git diff' not to produce textual output; the latter can go - through the line endings conversion process in repositories - with core.autocrlf set), expand and unexpand '$Id$' keyword - with blob object name, specify a custom 3-way merge driver, - and specify a custom diff driver. You can also apply - arbitrary filter to contents on check-in/check-out codepath - but this feature is an extremely sharp-edged razor and needs - to be handled with caution (do not use it unless you - understand the earlier mailing list discussion on keyword - expansion). These conversions apply when checking files in - or out, and exporting via git-archive. - -* The packfile format now optionally supports 64-bit index. - - This release supports the "version 2" format of the .idx - file. This is automatically enabled when a huge packfile - needs more than 32-bit to express offsets of objects in the - pack. - -* Comes with an updated git-gui 0.7.1 - -* Updated gitweb: - - - can show combined diff for merges; - - uses font size of user's preference, not hardcoded in pixels; - - can now 'grep'; - -* New commands and options. - - - "git bisect start" can optionally take a single bad commit and - zero or more good commits on the command line. - - - "git shortlog" can optionally be told to wrap its output. - - - "subtree" merge strategy allows another project to be merged in as - your subdirectory. - - - "git format-patch" learned a new --subject-prefix= - option, to override the built-in "[PATCH]". - - - "git add -u" is a quick way to do the first stage of "git - commit -a" (i.e. update the index to match the working - tree); it obviously does not make a commit. - - - "git clean" honors a new configuration, "clean.requireforce". When - set to true, this makes "git clean" a no-op, preventing you - from losing files by typing "git clean" when you meant to - say "make clean". You can still say "git clean -f" to - override this. - - - "git log" family of commands learned --date={local,relative,default} - option. --date=relative is synonym to the --relative-date. - --date=local gives the timestamp in local timezone. - -* Updated behavior of existing commands. - - - When $GIT_COMMITTER_EMAIL or $GIT_AUTHOR_EMAIL is not set - but $EMAIL is set, the latter is used as a substitute. - - - "git diff --stat" shows size of preimage and postimage blobs - for binary contents. Earlier it only said "Bin". - - - "git lost-found" shows stuff that are unreachable except - from reflogs. - - - "git checkout branch^0" now detaches HEAD at the tip commit - on the named branch, instead of just switching to the - branch (use "git checkout branch" to switch to the branch, - as before). - - - "git bisect next" can be used after giving only a bad commit - without giving a good one (this starts bisection half-way to - the root commit). We used to refuse to operate without a - good and a bad commit. - - - "git push", when pushing into more than one repository, does - not stop at the first error. - - - "git archive" does not insist you to give --format parameter - anymore; it defaults to "tar". - - - "git cvsserver" can use backends other than sqlite. - - - "gitview" (in contrib/ section) learned to better support - "git-annotate". - - - "git diff $commit1:$path2 $commit2:$path2" can now report - mode changes between the two blobs. - - - Local "git fetch" from a repository whose object store is - one of the alternates (e.g. fetching from the origin in a - repository created with "git clone -l -s") avoids - downloading objects unnecessarily. - - - "git blame" uses .mailmap to canonicalize the author name - just like "git shortlog" does. - - - "git pack-objects" pays attention to pack.depth - configuration variable. - - - "git cherry-pick" and "git revert" does not use .msg file in - the working tree to prepare commit message; instead it uses - $GIT_DIR/MERGE_MSG as other commands do. - -* Builds - - - git-p4import has never been installed; now there is an - installation option to do so. - - - gitk and git-gui can be configured out. - - - Generated documentation pages automatically get version - information from GIT_VERSION. - - - Parallel build with "make -j" descending into subdirectory - was fixed. - -* Performance Tweaks - - - Optimized "git-rev-list --bisect" (hence "git-bisect"). - - - Optimized "git-add $path" in a large directory, most of - whose contents are ignored. - - - Optimized "git-diff-tree" for reduced memory footprint. - - - The recursive merge strategy updated a worktree file that - was changed identically in two branches, when one of them - renamed it. We do not do that when there is no rename, so - match that behaviour. This avoids excessive rebuilds. - - - The default pack depth has been increased to 50, as the - recent addition of delta_base_cache makes deeper delta chains - much less expensive to access. Depending on the project, it was - reported that this reduces the resulting pack file by 10% - or so. - - -Fixes since v1.5.1 ------------------- - -All of the fixes in v1.5.1 maintenance series are included in -this release, unless otherwise noted. - -* Bugfixes - - - Switching branches with "git checkout" refused to work when - a path changes from a file to a directory between the - current branch and the new branch, in order not to lose - possible local changes in the directory that is being turned - into a file with the switch. We now allow such a branch - switch after making sure that there is no locally modified - file nor un-ignored file in the directory. This has not - been backported to 1.5.1.x series, as it is rather an - intrusive change. - - - Merging branches that have a file in one and a directory in - another at the same path used to get quite confused. We - handle such a case a bit more carefully, even though that is - still left as a conflict for the user to sort out. This - will not be backported to 1.5.1.x series, as it is rather an - intrusive change. - - - git-fetch had trouble with a remote with insanely large number - of refs. - - - "git clean -d -X" now does not remove non-excluded directories. - - - rebasing (without -m) a series that changes a symlink to a directory - in the middle of a path confused git-apply greatly and refused to - operate. diff --git a/Documentation/RelNotes/1.5.3.1.adoc b/Documentation/RelNotes/1.5.3.1.adoc deleted file mode 100644 index 7ff546c743b3ac..00000000000000 --- a/Documentation/RelNotes/1.5.3.1.adoc +++ /dev/null @@ -1,10 +0,0 @@ -GIT v1.5.3.1 Release Notes -========================== - -Fixes since v1.5.3 ------------------- - -This is solely to fix the generated RPM's dependencies. We used -to have git-p4 package but we do not anymore. As suggested on -the mailing list, this release makes git-core "Obsolete" git-p4, -so that yum update would not complain. diff --git a/Documentation/RelNotes/1.5.3.2.adoc b/Documentation/RelNotes/1.5.3.2.adoc deleted file mode 100644 index 4bbde3cab4dc6d..00000000000000 --- a/Documentation/RelNotes/1.5.3.2.adoc +++ /dev/null @@ -1,58 +0,0 @@ -GIT v1.5.3.2 Release Notes -========================== - -Fixes since v1.5.3.1 --------------------- - - * git-push sent thin packs by default, which was not good for - the public distribution server (no point in saving transfer - while pushing; no point in making the resulting pack less - optimum). - - * git-svn sometimes terminated with "Malformed network data" when - talking over svn:// protocol. - - * git-send-email re-issued the same message-id about 10% of the - time if you fired off 30 messages within a single second. - - * git-stash was not terminating the log message of commits it - internally creates with LF. - - * git-apply failed to check the size of the patch hunk when its - beginning part matched the remainder of the preimage exactly, - even though the preimage recorded in the hunk was much larger - (therefore the patch should not have applied), leading to a - segfault. - - * "git rm foo && git commit foo" complained that 'foo' needs to - be added first, instead of committing the removal, which was a - nonsense. - - * git grep -c said "/dev/null: 0". - - * git-add -u failed to recognize a blob whose type changed - between the index and the work tree. - - * The limit to rename detection has been tightened a lot to - reduce performance problems with a huge change. - - * cvsimport and svnimport barfed when the input tried to move - a tag. - - * "git apply -pN" did not chop the right number of directories. - - * "git svnimport" did not like SVN tags with funny characters in them. - - * git-gui 0.8.3, with assorted fixes, including: - - - font-chooser on X11 was unusable with large number of fonts; - - a diff that contained a deleted symlink made it barf; - - an untracked symbolic link to a directory made it fart; - - a file with % in its name made it vomit; - - -Documentation updates ---------------------- - -User manual has been somewhat restructured. I think the new -organization is much easier to read. diff --git a/Documentation/RelNotes/1.5.3.3.adoc b/Documentation/RelNotes/1.5.3.3.adoc deleted file mode 100644 index d2138469511d3d..00000000000000 --- a/Documentation/RelNotes/1.5.3.3.adoc +++ /dev/null @@ -1,31 +0,0 @@ -GIT v1.5.3.3 Release Notes -========================== - -Fixes since v1.5.3.2 --------------------- - - * git-quiltimport did not like it when a patch described in the - series file does not exist. - - * p4 importer missed executable bit in some cases. - - * The default shell on some FreeBSD did not execute the - argument parsing code correctly and made git unusable. - - * git-svn incorrectly spawned pager even when the user - explicitly asked not to. - - * sample post-receive hook overquoted the envelope sender - value. - - * git-am got confused when the patch contained a change that is - only about type and not contents. - - * git-mergetool did not show our and their version of the - conflicted file when started from a subdirectory of the - project. - - * git-mergetool did not pass correct options when invoking diff3. - - * git-log sometimes invoked underlying "diff" machinery - unnecessarily. diff --git a/Documentation/RelNotes/1.5.3.4.adoc b/Documentation/RelNotes/1.5.3.4.adoc deleted file mode 100644 index b04b3a45a5629c..00000000000000 --- a/Documentation/RelNotes/1.5.3.4.adoc +++ /dev/null @@ -1,35 +0,0 @@ -GIT v1.5.3.4 Release Notes -========================== - -Fixes since v1.5.3.3 --------------------- - - * Change to "git-ls-files" in v1.5.3.3 that was introduced to support - partial commit of removal better had a segfaulting bug, which was - diagnosed and fixed by Keith and Carl. - - * Performance improvements for rename detection has been backported - from the 'master' branch. - - * "git-for-each-ref --format='%(numparent)'" was not working - correctly at all, and --format='%(parent)' was not working for - merge commits. - - * Sample "post-receive-hook" incorrectly sent out push - notification e-mails marked as "From: " the committer of the - commit that happened to be at the tip of the branch that was - pushed, not from the person who pushed. - - * "git-remote" did not exit non-zero status upon error. - - * "git-add -i" did not respond very well to EOF from tty nor - bogus input. - - * "git-rebase -i" squash subcommand incorrectly made the - author of later commit the author of resulting commit, - instead of taking from the first one in the squashed series. - - * "git-stash apply --index" was not documented. - - * autoconfiguration learned that "ar" command is found as "gas" on - some systems. diff --git a/Documentation/RelNotes/1.5.3.5.adoc b/Documentation/RelNotes/1.5.3.5.adoc deleted file mode 100644 index 7ff1d5d0d100fc..00000000000000 --- a/Documentation/RelNotes/1.5.3.5.adoc +++ /dev/null @@ -1,94 +0,0 @@ -GIT v1.5.3.5 Release Notes -========================== - -Fixes since v1.5.3.4 --------------------- - - * Comes with git-gui 0.8.4. - - * "git-config" silently ignored options after --list; now it will - error out with a usage message. - - * "git-config --file" failed if the argument used a relative path - as it changed directories before opening the file. - - * "git-config --file" now displays a proper error message if it - cannot read the file specified on the command line. - - * "git-config", "git-diff", "git-apply" failed if run from a - subdirectory with relative GIT_DIR and GIT_WORK_TREE set. - - * "git-blame" crashed if run during a merge conflict. - - * "git-add -i" did not handle single line hunks correctly. - - * "git-rebase -i" and "git-stash apply" failed if external diff - drivers were used for one or more files in a commit. They now - avoid calling the external diff drivers. - - * "git-log --follow" did not work unless diff generation (e.g. -p) - was also requested. - - * "git-log --follow -B" did not work at all. Fixed. - - * "git-log -M -B" did not correctly handle cases of very large files - being renamed and replaced by very small files in the same commit. - - * "git-log" printed extra newlines between commits when a diff - was generated internally (e.g. -S or --follow) but not displayed. - - * "git-push" error message is more helpful when pushing to a - repository with no matching refs and none specified. - - * "git-push" now respects + (force push) on wildcard refspecs, - matching the behavior of git-fetch. - - * "git-filter-branch" now updates the working directory when it - has finished filtering the current branch. - - * "git-instaweb" no longer fails on Mac OS X. - - * "git-cvsexportcommit" didn't always create new parent directories - before trying to create new child directories. Fixed. - - * "git-fetch" printed a scary (but bogus) error message while - fetching a tag that pointed to a tree or blob. The error did - not impact correctness, only user perception. The bogus error - is no longer printed. - - * "git-ls-files --ignored" did not properly descend into non-ignored - directories that themselves contained ignored files if d_type - was not supported by the filesystem. This bug impacted systems - such as AFS. Fixed. - - * Git segfaulted when reading an invalid .gitattributes file. Fixed. - - * post-receive-email example hook was fixed for non-fast-forward - updates. - - * Documentation updates for supported (but previously undocumented) - options of "git-archive" and "git-reflog". - - * "make clean" no longer deletes the configure script that ships - with the git tarball, making multiple architecture builds easier. - - * "git-remote show origin" spewed a warning message from Perl - when no remote is defined for the current branch via - branch..remote configuration settings. - - * Building with NO_PERL_MAKEMAKER excessively rebuilt contents - of perl/ subdirectory by rewriting perl.mak. - - * http.sslVerify configuration settings were not used in scripted - Porcelains. - - * "git-add" leaked a bit of memory while scanning for files to add. - - * A few workarounds to squelch false warnings from recent gcc have - been added. - - * "git-send-pack $remote frotz" segfaulted when there is nothing - named 'frotz' on the local end. - - * "git-rebase --interactive" did not handle its "--strategy" option - properly. diff --git a/Documentation/RelNotes/1.5.3.6.adoc b/Documentation/RelNotes/1.5.3.6.adoc deleted file mode 100644 index 069a2b2cf9e9f2..00000000000000 --- a/Documentation/RelNotes/1.5.3.6.adoc +++ /dev/null @@ -1,48 +0,0 @@ -GIT v1.5.3.6 Release Notes -========================== - -Fixes since v1.5.3.5 --------------------- - - * git-cvsexportcommit handles root commits better. - - * git-svn dcommit used to clobber when sending a series of - patches. - - * git-svn dcommit failed after attempting to rebase when - started with a dirty index; now it stops upfront. - - * git-grep sometimes refused to work when your index was - unmerged. - - * "git-grep -A1 -B2" acted as if it was told to run "git -A1 -B21". - - * git-hash-object did not honor configuration variables, such as - core.compression. - - * git-index-pack choked on a huge pack on 32-bit machines, even when - large file offsets are supported. - - * atom feeds from git-web said "10" for the month of November. - - * a memory leak in commit walker was plugged. - - * When git-send-email inserted the original author's From: - address in body, it did not mark the message with - Content-type: as needed. - - * git-revert and git-cherry-pick incorrectly refused to start - when the work tree was dirty. - - * git-clean did not honor core.excludesfile configuration. - - * git-add mishandled ".gitignore" files when applying them to - subdirectories. - - * While importing a too branchy history, git-fastimport did not - honor delta depth limit properly. - - * Support for zlib implementations that lack ZLIB_VERNUM and definition - of deflateBound() has been added. - - * Quite a lot of documentation clarifications. diff --git a/Documentation/RelNotes/1.5.3.7.adoc b/Documentation/RelNotes/1.5.3.7.adoc deleted file mode 100644 index 2f690616c8327f..00000000000000 --- a/Documentation/RelNotes/1.5.3.7.adoc +++ /dev/null @@ -1,45 +0,0 @@ -GIT v1.5.3.7 Release Notes -========================== - -Fixes since v1.5.3.6 --------------------- - - * git-send-email added 8-bit contents to the payload without - marking it as 8-bit in a CTE header. - - * "git-bundle create a.bndl HEAD" dereferenced the symref and - did not record the ref as 'HEAD'; this prevented a bundle - from being used as a normal source of git-clone. - - * The code to reject nonsense command line of the form - "git-commit -a paths..." and "git-commit --interactive - paths..." were broken. - - * Adding a signature that is not ASCII-only to an original - commit that is ASCII-only would make the result non-ASCII. - "git-format-patch -s" did not mark such a message correctly - with MIME encoding header. - - * git-add sometimes did not mark the resulting index entry - stat-clean. This affected only cases when adding the - contents with the same length as the previously staged - contents, and the previous staging made the index entry - "racily clean". - - * git-commit did not honor GIT_INDEX_FILE the user had in the - environment. - - * When checking out a revision, git-checkout did not report where the - updated HEAD is if you happened to have a file called HEAD in the - work tree. - - * "git-rev-list --objects" mishandled a tree that points at a - submodule. - - * "git cvsimport" was not ready for packed refs that "git gc" can - produce and gave incorrect results. - - * Many scripted Porcelains were confused when you happened to have a - file called "HEAD" in your work tree. - -Also it contains updates to the user manual and documentation. diff --git a/Documentation/RelNotes/1.5.3.8.adoc b/Documentation/RelNotes/1.5.3.8.adoc deleted file mode 100644 index 0e3ff58a46f3cc..00000000000000 --- a/Documentation/RelNotes/1.5.3.8.adoc +++ /dev/null @@ -1,25 +0,0 @@ -GIT v1.5.3.8 Release Notes -========================== - -Fixes since v1.5.3.7 --------------------- - - * Some documentation used "email.com" as an example domain. - - * git-svn fix to handle funky branch and project names going over - http/https correctly. - - * git-svn fix to tone down a needlessly alarming warning message. - - * git-clone did not correctly report errors while fetching over http. - - * git-send-email added redundant Message-Id: header to the outgoing - e-mail when the patch text already had one. - - * a read-beyond-end-of-buffer bug in configuration file updater was fixed. - - * git-grep used to show the same hit repeatedly for unmerged paths. - - * After amending the patch title in "git-am -i", the command did not - report the patch it applied with the updated title. - diff --git a/Documentation/RelNotes/1.5.3.adoc b/Documentation/RelNotes/1.5.3.adoc deleted file mode 100644 index 0668d3c0cadc8e..00000000000000 --- a/Documentation/RelNotes/1.5.3.adoc +++ /dev/null @@ -1,366 +0,0 @@ -GIT v1.5.3 Release Notes -======================== - -Updates since v1.5.2 --------------------- - -* The commit walkers other than http are officially deprecated, - but still supported for now. - -* The submodule support has Porcelain layer. - - Note that the current submodule support is minimal and this is - deliberately so. A design decision we made is that operations - at the supermodule level do not recurse into submodules by - default. The expectation is that later we would add a - mechanism to tell git which submodules the user is interested - in, and this information might be used to determine the - recursive behaviour of certain commands (e.g. "git checkout" - and "git diff"), but currently we haven't agreed on what that - mechanism should look like. Therefore, if you use submodules, - you would probably need "git submodule update" on the - submodules you care about after running a "git checkout" at - the supermodule level. - -* There are a handful pack-objects changes to help you cope better - with repositories with pathologically large blobs in them. - -* For people who need to import from Perforce, a front-end for - fast-import is in contrib/fast-import/. - -* Comes with git-gui 0.8.2. - -* Comes with updated gitk. - -* New commands and options. - - - "git log --date=" can use more formats: iso8601, rfc2822. - - - The hunk header output from "git diff" family can be customized - with the attributes mechanism. See gitattributes(5) for details. - - - "git stash" allows you to quickly save away your work in - progress and replay it later on an updated state. - - - "git rebase" learned an "interactive" mode that let you - pick and reorder which commits to rebuild. - - - "git fsck" can save its findings in $GIT_DIR/lost-found, without a - separate invocation of "git lost-found" command. The blobs stored by - lost-found are stored in plain format to allow you to grep in them. - - - $GIT_WORK_TREE environment variable can be used together with - $GIT_DIR to work in a subdirectory of a working tree that is - not located at "$GIT_DIR/..". - - - Giving "--file=" option to "git config" is the same as - running the command with GIT_CONFIG= environment. - - - "git log" learned a new option "--follow", to follow - renaming history of a single file. - - - "git filter-branch" lets you rewrite the revision history of - specified branches. You can specify a number of filters to - modify the commits, files and trees. - - - "git cvsserver" learned new options (--base-path, --export-all, - --strict-paths) inspired by "git daemon". - - - "git daemon --base-path-relaxed" can help migrating a repository URL - that did not use to use --base-path to use --base-path. - - - "git commit" can use "-t templatefile" option and commit.template - configuration variable to prime the commit message given to you in the - editor. - - - "git submodule" command helps you manage the projects from - the superproject that contain them. - - - In addition to core.compression configuration option, - core.loosecompression and pack.compression options can - independently tweak zlib compression levels used for loose - and packed objects. - - - "git ls-tree -l" shows size of blobs pointed at by the - tree entries, similar to "/bin/ls -l". - - - "git rev-list" learned --regexp-ignore-case and - --extended-regexp options to tweak its matching logic used - for --grep filtering. - - - "git describe --contains" is a handier way to call more - obscure command "git name-rev --tags". - - - "git gc --aggressive" tells the command to spend more cycles - to optimize the repository harder. - - - "git repack" learned a "window-memory" limit which - dynamically reduces the window size to stay within the - specified memory usage. - - - "git repack" can be told to split resulting packs to avoid - exceeding limit specified with "--max-pack-size". - - - "git fsck" gained --verbose option. This is really really - verbose but it might help you identify exact commit that is - corrupt in your repository. - - - "git format-patch" learned --numbered-files option. This - may be useful for MH users. - - - "git format-patch" learned format.subjectprefix configuration - variable, which serves the same purpose as "--subject-prefix" - option. - - - "git tag -n -l" shows tag annotations while listing tags. - - - "git cvsimport" can optionally use the separate-remote layout. - - - "git blame" can be told to see through commits that change - whitespaces and indentation levels with "-w" option. - - - "git send-email" can be told not to thread the messages when - sending out more than one patches. - - - "git send-email" can also be told how to find whom to cc the - message to for each message via --cc-cmd. - - - "git config" learned NUL terminated output format via -z to - help scripts. - - - "git add" learned "--refresh ..." option to selectively refresh - the cached stat information. - - - "git init -q" makes the command quieter. - - - "git -p command" now has a cousin of opposite sex, "git --no-pager - command". - -* Updated behavior of existing commands. - - - "gitweb" can offer multiple snapshot formats. - - ***NOTE*** Unfortunately, this changes the format of the - $feature{snapshot}{default} entry in the per-site - configuration file 'gitweb_config.perl'. It used to be a - three-element tuple that describe a single format; with the - new configuration item format, you only have to say the name - of the format ('tgz', 'tbz2' or 'zip'). Please update the - your configuration file accordingly. - - - "git clone" uses -l (hardlink files under .git) by default when - cloning locally. - - - URL used for "git clone" and friends can specify nonstandard SSH port - by using ssh://host:port/path/to/repo syntax. - - - "git bundle create" can now create a bundle without negative refs, - i.e. "everything since the beginning up to certain points". - - - "git diff" (but not the plumbing level "git diff-tree") now - recursively descends into trees by default. - - - "git diff" does not show differences that come only from - stat-dirtiness in the form of "diff --git" header anymore. - It runs "update-index --refresh" silently as needed. - - - "git tag -l" used to match tags by globbing its parameter as if it - has wildcard '*' on both ends, which made "git tag -l gui" to match - tag 'gitgui-0.7.0'; this was very annoying. You now have to add - asterisk on the sides you want to wildcard yourself. - - - The editor to use with many interactive commands can be - overridden with GIT_EDITOR environment variable, or if it - does not exist, with core.editor configuration variable. As - before, if you have neither, environment variables VISUAL - and EDITOR are consulted in this order, and then finally we - fall back on "vi". - - - "git rm --cached" does not complain when removing a newly - added file from the index anymore. - - - Options to "git log" to affect how --grep/--author options look for - given strings now have shorter abbreviations. -i is for ignore case, - and -E is for extended regexp. - - - "git log" learned --log-size to show the number of bytes in - the log message part of the output to help qgit. - - - "git log --name-status" does not require you to give "-r" anymore. - As a general rule, Porcelain commands should recurse when showing - diff. - - - "git format-patch --root A" can be used to format everything - since the beginning up to A. This was supported with - "git format-patch --root A A" for a long time, but was not - properly documented. - - - "git svn dcommit" retains local merge information. - - - "git svnimport" allows an empty string to be specified as the - trunk/ directory. This is necessary to suck data from a SVN - repository that doe not have trunk/ branches/ and tags/ organization - at all. - - - "git config" to set values also honors type flags like --bool - and --int. - - - core.quotepath configuration can be used to make textual git - output to emit most of the characters in the path literally. - - - "git mergetool" chooses its backend more wisely, taking - notice of its environment such as use of X, Gnome/KDE, etc. - - - "gitweb" shows merge commits a lot nicer than before. The - default view uses more compact --cc format, while the UI - allows to choose normal diff with any parent. - - - snapshot files "gitweb" creates from a repository at - $path/$project/.git are more useful. We use $project part - in the filename, which we used to discard. - - - "git cvsimport" creates lightweight tags; there is no - interesting information we can record in an annotated tag, - and the handcrafted ones the old code created was not - properly formed anyway. - - - "git push" pretends that you immediately fetched back from - the remote by updating corresponding remote tracking - branches if you have any. - - - The diffstat given after a merge (or a pull) honors the - color.diff configuration. - - - "git commit --amend" is now compatible with various message source - options such as -m/-C/-c/-F. - - - "git apply --whitespace=strip" removes blank lines added at - the end of the file. - - - "git fetch" over git native protocols with "-v" option shows - connection status, and the IP address of the other end, to - help diagnosing problems. - - - We used to have core.legacyheaders configuration, when - set to false, allowed git to write loose objects in a format - that mimics the format used by objects stored in packs. It - turns out that this was not so useful. Although we will - continue to read objects written in that format, we do not - honor that configuration anymore and create loose objects in - the legacy/traditional format. - - - "--find-copies-harder" option to diff family can now be - spelled as "-C -C" for brevity. - - - "git mailsplit" (hence "git am") can read from Maildir - formatted mailboxes. - - - "git cvsserver" does not barf upon seeing "cvs login" - request. - - - "pack-objects" honors "delta" attribute set in - .gitattributes. It does not attempt to deltify blobs that - come from paths with delta attribute set to false. - - - "new-workdir" script (in contrib) can now be used with a - bare repository. - - - "git mergetool" learned to use gvimdiff. - - - "gitview" (in contrib) has a better blame interface. - - - "git log" and friends did not handle a commit log message - that is larger than 16kB; they do now. - - - "--pretty=oneline" output format for "git log" and friends - deals with "malformed" commit log messages that have more - than one lines in the first paragraph better. We used to - show the first line, cutting the title at mid-sentence; we - concatenate them into a single line and treat the result as - "oneline". - - - "git p4import" has been demoted to contrib status. For - a superior option, checkout the "git p4" front end to - "git fast-import" (also in contrib). The man page and p4 - rpm have been removed as well. - - - "git mailinfo" (hence "am") now tries to see if the message - is in utf-8 first, instead of assuming iso-8859-1, if - incoming e-mail does not say what encoding it is in. - -* Builds - - - old-style function definitions (most notably, a function - without parameter defined with "func()", not "func(void)") - have been eradicated. - - - "git tag" and "git verify-tag" have been rewritten in C. - -* Performance Tweaks - - - "git pack-objects" avoids re-deltification cost by caching - small enough delta results it creates while looking for the - best delta candidates. - - - "git pack-objects" learned a new heuristic to prefer delta - that is shallower in depth over the smallest delta - possible. This improves both overall packfile access - performance and packfile density. - - - diff-delta code that is used for packing has been improved - to work better on big files. - - - when there are more than one pack files in the repository, - the runtime used to try finding an object always from the - newest packfile; it now tries the same packfile as we found - the object requested the last time, which exploits the - locality of references. - - - verifying pack contents done by "git fsck --full" got boost - by carefully choosing the order to verify objects in them. - - - "git read-tree -m" to read into an already populated index - has been optimized vastly. The effect of this can be seen - when switching branches that have differences in only a - handful paths. - - - "git add paths..." and "git commit paths..." has also been - heavily optimized. - -Fixes since v1.5.2 ------------------- - -All of the fixes in v1.5.2 maintenance series are included in -this release, unless otherwise noted. - -* Bugfixes - - - "gitweb" had trouble handling non UTF-8 text with older - Encode.pm Perl module. - - - "git svn" misparsed the data from the commits in the repository when - the user had "color.diff = true" in the configuration. This has been - fixed. - - - There was a case where "git svn dcommit" clobbered changes made on the - SVN side while committing multiple changes. - - - "git-write-tree" had a bad interaction with racy-git avoidance and - gitattributes mechanisms. - - - "git --bare command" overrode existing GIT_DIR setting and always - made it treat the current working directory as GIT_DIR. - - - "git ls-files --error-unmatch" does not complain if you give the - same path pattern twice by mistake. - - - "git init" autodetected core.filemode but not core.symlinks, which - made a new directory created automatically by "git clone" cumbersome - to use on filesystems that require these configurations to be set. - - - "git log" family of commands behaved differently when run as "git - log" (no pathspec) and as "git log --" (again, no pathspec). This - inconsistency was introduced somewhere in v1.3.0 series but now has - been corrected. - - - "git rebase -m" incorrectly displayed commits that were skipped. diff --git a/Documentation/RelNotes/1.5.4.1.adoc b/Documentation/RelNotes/1.5.4.1.adoc deleted file mode 100644 index d4e44b8b09d717..00000000000000 --- a/Documentation/RelNotes/1.5.4.1.adoc +++ /dev/null @@ -1,17 +0,0 @@ -GIT v1.5.4.1 Release Notes -========================== - -Fixes since v1.5.4 ------------------- - - * "git-commit -C $tag" used to work but rewrite in C done in - 1.5.4 broke it. - - * An entry in the .gitattributes file that names a pattern in a - subdirectory of the directory it is in did not match - correctly (e.g. pattern "b/*.c" in "a/.gitattributes" should - match "a/b/foo.c" but it didn't). - - * Customized color specification was parsed incorrectly when - numeric color values are used. This was fixed in 1.5.4.1. - diff --git a/Documentation/RelNotes/1.5.4.2.adoc b/Documentation/RelNotes/1.5.4.2.adoc deleted file mode 100644 index 21d0df59fbb08a..00000000000000 --- a/Documentation/RelNotes/1.5.4.2.adoc +++ /dev/null @@ -1,43 +0,0 @@ -GIT v1.5.4.2 Release Notes -========================== - -Fixes since v1.5.4 ------------------- - - * The configuration parser was not prepared to see string - valued variables misspelled as boolean and segfaulted. - - * Temporary files left behind due to interrupted object - transfers were not cleaned up with "git prune". - - * "git config --unset" was confused when the unset variables - were spelled with continuation lines in the config file. - - * The merge message detection in "git cvsimport" did not catch - a message that began with "Merge...". - - * "git status" suggests "git rm --cached" for unstaging the - earlier "git add" before the initial commit. - - * "git status" output was incorrect during a partial commit. - - * "git bisect" refused to start when the HEAD was detached. - - * "git bisect" allowed a wildcard character in the commit - message expanded while writing its log file. - - * Manual pages were not formatted correctly with docbook xsl - 1.72; added a workaround. - - * "git-commit -C $tag" used to work but rewrite in C done in - 1.5.4 broke it. This was fixed in 1.5.4.1. - - * An entry in the .gitattributes file that names a pattern in a - subdirectory of the directory it is in did not match - correctly (e.g. pattern "b/*.c" in "a/.gitattributes" should - match "a/b/foo.c" but it didn't). This was fixed in 1.5.4.1. - - * Customized color specification was parsed incorrectly when - numeric color values are used. This was fixed in 1.5.4.1. - - * http transport misbehaved when linked with curl-gnutls. diff --git a/Documentation/RelNotes/1.5.4.3.adoc b/Documentation/RelNotes/1.5.4.3.adoc deleted file mode 100644 index b0fc67fb2ade1c..00000000000000 --- a/Documentation/RelNotes/1.5.4.3.adoc +++ /dev/null @@ -1,27 +0,0 @@ -GIT v1.5.4.3 Release Notes -========================== - -Fixes since v1.5.4.2 --------------------- - - * RPM spec used to pull in everything with 'git'. This has been - changed so that 'git' package contains just the core parts, - and we now supply 'git-all' metapackage to slurp in everything. - This should match end user's expectation better. - - * When some refs failed to update, git-push reported "failure" - which was unclear if some other refs were updated or all of - them failed atomically (the answer is the former). Reworded - the message to clarify this. - - * "git clone" from a repository whose HEAD was misconfigured - did not set up the remote properly. Now it tries to do - better. - - * Updated git-push documentation to clarify what "matching" - means, in order to reduce user confusion. - - * Updated git-add documentation to clarify "add -u" operates in - the current subdirectory you are in, just like other commands. - - * git-gui updates to work on OSX and Windows better. diff --git a/Documentation/RelNotes/1.5.4.4.adoc b/Documentation/RelNotes/1.5.4.4.adoc deleted file mode 100644 index 323c1a88c7fe2b..00000000000000 --- a/Documentation/RelNotes/1.5.4.4.adoc +++ /dev/null @@ -1,66 +0,0 @@ -GIT v1.5.4.4 Release Notes -========================== - -Fixes since v1.5.4.3 --------------------- - - * Building and installing with an overtight umask such as 077 made - installed templates unreadable by others, while the rest of the install - are done in a way that is friendly to umask 022. - - * "git cvsexportcommit -w $cvsdir" misbehaved when GIT_DIR is set to a - relative directory. - - * "git http-push" had an invalid memory access that could lead it to - segfault. - - * When "git rebase -i" gave control back to the user for a commit that is - marked to be edited, it just said "modify it with commit --amend", - without saying what to do to continue after modifying it. Give an - explicit instruction to run "rebase --continue" to be more helpful. - - * "git send-email" in 1.5.4.3 issued a bogus empty In-Reply-To: header. - - * "git bisect" showed mysterious "won't bisect on seeked tree" error message. - This was leftover from Cogito days to prevent "bisect" starting from a - cg-seeked state. We still keep the Cogito safety, but running "git bisect - start" when another bisect was in effect will clean up and start over. - - * "git push" with an explicit PATH to receive-pack did not quite work if - receive-pack was not on usual PATH. We earlier fixed the same issue - with "git fetch" and upload-pack, but somehow forgot to do so in the - other direction. - - * git-gui's info dialog was not displayed correctly when the user tries - to commit nothing (i.e. without staging anything). - - * "git revert" did not properly fail when attempting to run with a - dirty index. - - * "git merge --no-commit --no-ff " incorrectly made commits. - - * "git merge --squash --no-ff ", which is a nonsense combination - of options, was not rejected. - - * "git ls-remote" and "git remote show" against an empty repository - failed, instead of just giving an empty result (regression). - - * "git fast-import" did not handle a renamed path whose name needs to be - quoted, due to a bug in unquote_c_style() function. - - * "git cvsexportcommit" was confused when multiple files with the same - basename needed to be pushed out in the same commit. - - * "git daemon" did not send early errors to syslog. - - * "git log --merge" did not work well with --left-right option. - - * "git svn" prompted for client cert password every time it accessed the - server. - - * The reset command in "git fast-import" data stream was documented to - end with an optional LF, but it actually required one. - - * "git svn dcommit/rebase" did not honor --rewrite-root option. - -Also included are a handful documentation updates. diff --git a/Documentation/RelNotes/1.5.4.5.adoc b/Documentation/RelNotes/1.5.4.5.adoc deleted file mode 100644 index bbd130e36d411e..00000000000000 --- a/Documentation/RelNotes/1.5.4.5.adoc +++ /dev/null @@ -1,56 +0,0 @@ -GIT v1.5.4.5 Release Notes -========================== - -Fixes since v1.5.4.4 --------------------- - - * "git fetch there" when the URL information came from the Cogito style - branches/there file did not update refs/heads/there (regression in - 1.5.4). - - * Bogus refspec configuration such as "remote.there.fetch = =" were not - detected as errors (regression in 1.5.4). - - * You couldn't specify a custom editor whose path contains a whitespace - via GIT_EDITOR (and core.editor). - - * The subdirectory filter to "git filter-branch" mishandled a history - where the subdirectory becomes empty and then later becomes non-empty. - - * "git shortlog" gave an empty line if the original commit message was - malformed (e.g. a botched import from foreign SCM). Now it finds the - first non-empty line and uses it for better information. - - * When the user fails to give a revision parameter to "git svn", an error - from the Perl interpreter was issued because the script lacked proper - error checking. - - * After "git rebase" stopped due to conflicts, if the user played with - "git reset" and friends, "git rebase --abort" failed to go back to the - correct commit. - - * Additional work trees prepared with git-new-workdir (in contrib/) did - not share git-svn metadata directory .git/svn with the original. - - * "git-merge-recursive" did not mark addition of the same path with - different filemodes correctly as a conflict. - - * "gitweb" gave malformed URL when pathinfo stype paths are in use. - - * "-n" stands for "--no-tags" again for "git fetch". - - * "git format-patch" did not detect the need to add 8-bit MIME header - when the user used format.header configuration. - - * "rev~" revision specifier used to mean "rev", which was inconsistent - with how "rev^" worked. Now "rev~" is the same as "rev~1" (hence it - also is the same as "rev^1"), and "rev~0" is the same as "rev^0" - (i.e. it has to be a commit). - - * "git quiltimport" did not grok empty lines, lines in "file -pNNN" - format to specify the prefix levels and lines with trailing comments. - - * "git rebase -m" triggered pre-commit verification, which made - "rebase --continue" impossible. - -As usual, it also comes with many documentation fixes and clarifications. diff --git a/Documentation/RelNotes/1.5.4.6.adoc b/Documentation/RelNotes/1.5.4.6.adoc deleted file mode 100644 index 3e3c3e55a31fd7..00000000000000 --- a/Documentation/RelNotes/1.5.4.6.adoc +++ /dev/null @@ -1,43 +0,0 @@ -GIT v1.5.4.6 Release Notes -========================== - -I personally do not think there is any reason anybody should want to -run v1.5.4.X series these days, because 'master' version is always -more stable than any tagged released version of git. - -This is primarily to futureproof "git-shell" to accept requests -without a dash between "git" and subcommand name (e.g. "git -upload-pack") which the newer client will start to make sometime in -the future. - -Fixes since v1.5.4.5 --------------------- - - * Command line option "-n" to "git-repack" was not correctly parsed. - - * Error messages from "git-apply" when the patchfile cannot be opened - have been improved. - - * Error messages from "git-bisect" when given nonsense revisions have - been improved. - - * reflog syntax that uses time e.g. "HEAD@{10 seconds ago}:path" did not - stop parsing at the closing "}". - - * "git rev-parse --symbolic-full-name ^master^2" printed solitary "^", - but it should print nothing. - - * "git apply" did not enforce "match at the beginning" correctly. - - * a path specification "a/b" in .gitattributes file should not match - "sub/a/b", but it did. - - * "git log --date-order --topo-order" did not override the earlier - date-order with topo-order as expected. - - * "git fast-export" did not export octopus merges correctly. - - * "git archive --prefix=$path/" mishandled gitattributes. - -As usual, it also comes with many documentation fixes and clarifications. - diff --git a/Documentation/RelNotes/1.5.4.7.adoc b/Documentation/RelNotes/1.5.4.7.adoc deleted file mode 100644 index 9065a0e27346b0..00000000000000 --- a/Documentation/RelNotes/1.5.4.7.adoc +++ /dev/null @@ -1,10 +0,0 @@ -GIT v1.5.4.7 Release Notes -========================== - -Fixes since 1.5.4.7 -------------------- - - * Removed support for an obsolete gitweb request URI, whose - implementation ran "git diff" Porcelain, instead of using plumbing, - which would have run an external diff command specified in the - repository configuration as the gitweb user. diff --git a/Documentation/RelNotes/1.5.4.adoc b/Documentation/RelNotes/1.5.4.adoc deleted file mode 100644 index f1323b61746ee5..00000000000000 --- a/Documentation/RelNotes/1.5.4.adoc +++ /dev/null @@ -1,377 +0,0 @@ -GIT v1.5.4 Release Notes -======================== - -Removal -------- - - * "git svnimport" was removed in favor of "git svn". It is still there - in the source tree (contrib/examples) but unsupported. - - * As git-commit and git-status have been rewritten, "git runstatus" - helper script lost all its users and has been removed. - - -Temporarily disabled --------------------- - - * "git http-push" is known not to work well with cURL library older - than 7.16, and we had reports of repository corruption. It is - disabled on such platforms for now. Unfortunately, 1.5.3.8 shares - the same issue. In other words, this does not mean you will be - fine if you stick to an older git release. For now, please do not - use http-push from older git with cURL older than 7.16 if you - value your data. A proper fix will hopefully materialize in - later versions. - - -Deprecation notices -------------------- - - * From v1.6.0, git will by default install dashed form of commands - (e.g. "git-commit") outside of users' normal $PATH, and will install - only selected commands ("git" itself, and "gitk") in $PATH. This - implies: - - - Using dashed forms of git commands (e.g. "git-commit") from the - command line has been informally deprecated since early 2006, but - now it officially is, and will be removed in the future. Use - dash-less forms (e.g. "git commit") instead. - - - Using dashed forms from your scripts, without first prepending the - return value from "git --exec-path" to the scripts' PATH, has been - informally deprecated since early 2006, but now it officially is. - - - Use of dashed forms with "PATH=$(git --exec-path):$PATH; export - PATH" early in your script is not deprecated with this change. - - Users are strongly encouraged to adjust their habits and scripts now - to prepare for this change. - - * The post-receive hook was introduced in March 2007 to supersede - the post-update hook, primarily to overcome the command line length - limitation of the latter. Use of post-update hook will be deprecated - in future versions of git, starting from v1.6.0. - - * "git lost-found" was deprecated in favor of "git fsck"'s --lost-found - option, and will be removed in the future. - - * "git peek-remote" is deprecated, as "git ls-remote" was written in C - and works for all transports; "git peek-remote" will be removed in - the future. - - * "git repo-config" which was an old name for "git config" command - has been supported without being advertised for a long time. The - next feature release will remove it. - - * From v1.6.0, the repack.usedeltabaseoffset config option will default - to true, which will give denser packfiles (i.e. more efficient storage). - The downside is that git older than version 1.4.4 will not be able - to directly use a repository packed using this setting. - - * From v1.6.0, the pack.indexversion config option will default to 2, - which is slightly more efficient, and makes repacking more immune to - data corruptions. Git older than version 1.5.2 may revert to version 1 - of the pack index with a manual "git index-pack" to be able to directly - access corresponding pack files. - - -Updates since v1.5.3 --------------------- - - * Comes with much improved gitk, with i18n. - - * Comes with git-gui 0.9.2 with i18n. - - * gitk is now merged as a subdirectory of git.git project, in - preparation for its i18n. - - * progress displays from many commands are a lot nicer to the eye. - Transfer commands show throughput data. - - * many commands that pay attention to per-directory .gitignore now do - so lazily, which makes the usual case go much faster. - - * Output processing for '--pretty=format:' has been - optimized. - - * Rename detection of diff family while detecting exact matches has - been greatly optimized. - - * Rename detection of diff family tries to make more natural looking - pairing. Earlier, if multiple identical rename sources were - found in the preimage, the source used was picked pretty much at random. - - * Value "true" for color.diff and color.status configuration used to - mean "always" (even when the output is not going to a terminal). - This has been corrected to mean the same thing as "auto". - - * "git diff" Porcelain now respects diff.external configuration, which - is another way to specify GIT_EXTERNAL_DIFF. - - * "git diff" can be told to use different prefixes other than - "a/" and "b/" e.g. "git diff --src-prefix=l/ --dst-prefix=k/". - - * "git diff" sometimes did not quote paths with funny - characters properly. - - * "git log" (and any revision traversal commands) misbehaved - when --diff-filter is given but was not asked to actually - produce diff. - - * HTTP proxy can be specified per remote repository using - remote.*.httpproxy configuration, or global http.proxy configuration - variable. - - * Various Perforce importer updates. - - * Example update and post-receive hooks have been improved. - - * Any command that wants to take a commit object name can now use - ":/string" syntax to name a commit. - - * "git reset" is now built-in and its output can be squelched with -q. - - * "git reset --hard" does not make any sense in a bare - repository, but did not error out; fixed. - - * "git send-email" can optionally talk over ssmtp and use SMTP-AUTH. - - * "git rebase" learned --whitespace option. - - * In "git rebase", when you decide not to replay a particular change - after the command stopped with a conflict, you can say "git rebase - --skip" without first running "git reset --hard", as the command now - runs it for you. - - * "git rebase --interactive" mode can now work on detached HEAD. - - * Other minor to serious bugs in "git rebase -i" have been fixed. - - * "git rebase" now detaches head during its operation, so after a - successful "git rebase" operation, the reflog entry branch@{1} for - the current branch points at the commit before the rebase was - started. - - * "git rebase -i" also triggers rerere to help your repeated merges. - - * "git merge" can call the "post-merge" hook. - - * "git pack-objects" can optionally run deltification with multiple - threads. - - * "git archive" can optionally substitute keywords in files marked with - export-subst attribute. - - * "git cherry-pick" made a misguided attempt to repeat the original - command line in the generated log message, when told to cherry-pick a - commit by naming a tag that points at it. It does not anymore. - - * "git for-each-ref" learned %(xxxdate:) syntax to show the - various date fields in different formats. - - * "git gc --auto" is a low-impact way to automatically run a variant of - "git repack" that does not lose unreferenced objects (read: safer - than the usual one) after the user accumulates too many loose - objects. - - * "git clean" has been rewritten in C. - - * You need to explicitly set clean.requireForce to "false" to allow - "git clean" without -f to do any damage (lack of the configuration - variable used to mean "do not require -f option to lose untracked - files", but we now use the safer default). - - * The kinds of whitespace errors "git diff" and "git apply" notice (and - fix) can be controlled via 'core.whitespace' configuration variable - and 'whitespace' attribute in .gitattributes file. - - * "git push" learned --dry-run option to show what would happen if a - push is run. - - * "git push" does not update a tracking ref on the local side when the - remote refused to update the corresponding ref. - - * "git push" learned --mirror option. This is to push the local refs - one-to-one to the remote, and deletes refs from the remote that do - not exist anymore in the repository on the pushing side. - - * "git push" can remove a corrupt ref at the remote site with the usual - ":ref" refspec. - - * "git remote" knows --mirror mode. This is to set up configuration to - push into a remote repository to store local branch heads to the same - branch on the remote side, and remove branch heads locally removed - from local repository at the same time. Suitable for pushing into a - back-up repository. - - * "git remote" learned "rm" subcommand. - - * "git cvsserver" can be run via "git shell". Also, "cvs" is - recognized as a synonym for "git cvsserver", so that CVS users - can be switched to git just by changing their login shell. - - * "git cvsserver" acts more like receive-pack by running post-receive - and post-update hooks. - - * "git am" and "git rebase" are far less verbose. - - * "git pull" learned to pass --[no-]ff option to underlying "git - merge". - - * "git pull --rebase" is a different way to integrate what you fetched - into your current branch. - - * "git fast-export" produces data-stream that can be fed to fast-import - to reproduce the history recorded in a git repository. - - * "git add -i" takes pathspecs to limit the set of files to work on. - - * "git add -p" is a short-hand to go directly to the selective patch - subcommand in the interactive command loop and to exit when done. - - * "git add -i" UI has been colorized. The interactive prompt - and menu can be colored by setting color.interactive - configuration. The diff output (including the hunk picker) - are colored with color.diff configuration. - - * "git commit --allow-empty" allows you to create a single-parent - commit that records the same tree as its parent, overriding the usual - safety valve. - - * "git commit --amend" can amend a merge that does not change the tree - from its first parent. - - * "git commit" used to unconditionally strip comment lines that - began with '#' and removed excess blank lines. This behavior has - been made configurable. - - * "git commit" has been rewritten in C. - - * "git stash random-text" does not create a new stash anymore. It was - a UI mistake. Use "git stash save random-text", or "git stash" - (without extra args) for that. - - * "git stash clear extra-text" does not clear the whole stash - anymore. It is tempting to expect "git stash clear stash@{2}" - to drop only a single named stash entry, and it is rude to - discard everything when that is asked (but not provided). - - * "git prune --expire