### Example: Start Bisect for Performance Regression

Source: https://github.com/git/htmldocs/blob/gh-pages/git-bisect.adoc

An example of starting a bisect session to find a performance regression, using 'fast' and 'slow' as custom terms.

```bash
git bisect start --term-old fast --term-new slow
```

--------------------------------

### Example: Start Bisect for Bug Fix

Source: https://github.com/git/htmldocs/blob/gh-pages/git-bisect.adoc

An example of starting a bisect session to find a bug fix, using 'broken' and 'fixed' as custom terms.

```bash
git bisect start --term-new fixed --term-old broken
```

--------------------------------

### Advanced Revision Walk Setup

Source: https://github.com/git/htmldocs/blob/gh-pages/MyFirstObjectWalk.adoc

Use 'struct setup_revision_opt' for finer control over the walk's starting point. This allows specifying commit-ish arguments and other options.

```c
struct setup_revision_opt opt;

memset(&opt, 0, sizeof(opt));
opt.def = "HEAD";
opt.revarg_opt = REVARG_COMMITTISH;
setup_revisions(argc, argv, rev, &opt);
```

--------------------------------

### Example of Git Bisect Starting a Search

Source: https://github.com/git/htmldocs/blob/gh-pages/git-bisect-lk2009.adoc

This example shows the output after starting a git bisect session with specific version tags. It indicates the number of revisions left to test and the commit being checked out.

```bash
$ git bisect start v2.6.27 v2.6.25
Bisecting: 10928 revisions left to test after this (roughly 14 steps)
[2ec65f8b89ea003c27ff7723525a2ee335a2b393] x86: clean up using max_low_pfn on 32-bit
```

--------------------------------

### Trace2 API Initialization Example

Source: https://github.com/git/htmldocs/blob/gh-pages/technical/api-trace2.adoc

This C code demonstrates the basic initialization of the Trace2 API within a main function. It registers handlers and starts command tracing.

```c
int main(int argc, const char **argv)
{
	int exit_code;


trace2_initialize();

trace2_cmd_start(argv);

	exit_code = cmd_main(argc, argv);


trace2_cmd_exit(exit_code);

	return exit_code;
}
```

--------------------------------

### Gitweb Configuration Example

Source: https://github.com/git/htmldocs/blob/gh-pages/gitweb.conf.html

This is an example of a gitweb configuration file. It demonstrates the basic syntax for setting variables and includes a comment.

```perl
# gitweb configuration file for http://git.example.org
```

--------------------------------

### Start Event Structure

Source: https://github.com/git/htmldocs/blob/gh-pages/technical/api-trace2.html

The 'start' event captures the complete command-line arguments received by the main process.

```json
{
        "event":"start",
        ...
        "t_abs":0.001227, # elapsed time in seconds
        "argv":["git","version"]
}
```

--------------------------------

### Systemd Timer Wants Directory Example

Source: https://github.com/git/htmldocs/blob/gh-pages/git-maintenance.adoc

Example of a directory containing symbolic links to activate Git maintenance timers. These links are typically managed by `git maintenance start` and ensure timers are started when the system boots or timers.target is activated.

```systemd
~/.config/systemd/user/timers.target.wants/git-maintenance@hourly.timer
```

```systemd
~/.config/systemd/user/timers.target.wants/git-maintenance@daily.timer
```

```systemd
~/.config/systemd/user/timers.target.wants/git-maintenance@weekly.timer
```

--------------------------------

### git show - Examples

Source: https://github.com/git/htmldocs/blob/gh-pages/git-show.adoc

Illustrative examples of using the git show command for various scenarios.

```APIDOC
## git show - Examples

### Examples

`git show v1.0.0`::
	Shows the tag `v1.0.0`, along with the object the tag points at.

`git show v1.0.0^{tree}`::
	Shows the tree pointed to by the tag `v1.0.0`.

`git show -s --format=%s v1.0.0^{commit}`::
	Shows the subject of the commit pointed to by the tag `v1.0.0`.

`git show next~10:Documentation/README`::
	Shows the contents of the file `Documentation/README` as they were current in the 10th last commit of the branch `next`.

`git show master:Makefile master:t/Makefile`::
	Concatenates the contents of said Makefiles in the head of the branch `master`.
```

--------------------------------

### Start Event with Arguments

Source: https://github.com/git/htmldocs/blob/gh-pages/technical/api-trace2.adoc

The 'start' event captures the complete argv received by the main() function, including the 't_abs' field for elapsed time.

```json
{
	"event":"start",
	...
	"t_abs":0.001227, # elapsed time in seconds
	"argv":["git","version"]
}
```

--------------------------------

### Trace2 Fetch Command Example

Source: https://github.com/git/htmldocs/blob/gh-pages/technical/api-trace2.adoc

Example of a git fetch command and its corresponding Trace2 log output, showing child process timings.

```shell
$ export GIT_TRACE2_BRIEF=1
$ export GIT_TRACE2=~/log.normal
$ git fetch origin
...

```

```shell
$ cat ~/log.normal
version 2.20.1.vfs.1.1.47.g534dbe1ad1
start git fetch origin
worktree /Users/jeffhost/work/gfw
cmd_name fetch (fetch)
child_start[0] ssh git@github.com ...
child_start[1] git index-pack ...
... (Trace2 events from child processes omitted)
child_exit[1] pid:14707 code:0 elapsed:0.076353
child_exit[0] pid:14706 code:0 elapsed:4.931869
child_start[2] git rev-list ...
... (Trace2 events from child process omitted)
child_exit[2] pid:14708 code:0 elapsed:0.110605
child_start[3] git gc --auto
... (Trace2 events from child process omitted)
child_exit[3] pid:14709 code:0 elapsed:0.006240
exit elapsed:5.198503 code:0
atexit elapsed:5.198541 code:0

```

--------------------------------

### Basic Gitweb Configuration Example

Source: https://github.com/git/htmldocs/blob/gh-pages/gitweb.conf.adoc

This is a basic example of a gitweb configuration file. It sets the base URL for the Gitweb interface. Comments are ignored.

```perl
# gitweb configuration file for http://git.example.org

```

--------------------------------

### Clone a Repository and Create Topic Branches

Source: https://github.com/git/htmldocs/blob/gh-pages/howto/keep-canonical-history-correct.html

This example shows the initial steps for setting up a development environment. It involves cloning a repository, checking out the main branch, and then creating new topic branches for separate lines of development.

```git
git clone $URL work && cd work
git checkout -b topic-b master
git checkout -b topic-c master
```

--------------------------------

### Initialize Example Repositories for Submodules

Source: https://github.com/git/htmldocs/blob/gh-pages/user-manual.html

This script initializes four separate Git repositories, each containing a single text file. These repositories serve as examples for later use as submodules.

```bash
mkdir ~/git
cd ~/git
for i in a b c d
do
        mkdir $i
        cd $i
        git init
        echo "module $i" > $i.txt
        git add $i.txt
        git commit -m "Initial commit, submodule $i"
        cd ..
done
```

--------------------------------

### Example .gitignore for vmlinux files

Source: https://github.com/git/htmldocs/blob/gh-pages/gitignore.html

This example shows a .gitignore file that ignores files starting with 'vmlinux'.

```gitattributes
vmlinux*
```

--------------------------------

### Initialize a new Git repository and create initial history

Source: https://github.com/git/htmldocs/blob/gh-pages/gittutorial-2.adoc

Use these commands to start a new project, add a file, and make the first commit. The commit hash will vary.

```bash
mkdir test-project
cd test-project
git init
Initialized empty Git repository in .git/
echo 'hello world' > file.txt
git add .
git commit -a -m "initial commit"
[master (root-commit) 54196cc] initial commit
 1 file changed, 1 insertion(+)
 create mode 100644 file.txt
echo 'hello world!' >file.txt
git commit -a -m "add emphasis"
[master c4d59f3] add emphasis
 1 file changed, 1 insertion(+), 1 deletion(-)
```

--------------------------------

### Setup Filter Example

Source: https://github.com/git/htmldocs/blob/gh-pages/git-filter-branch.adoc

The --setup filter is a one-time setup command executed before the main filtering loop. It can define functions or variables for subsequent filters.

```bash
--setup <command>
```

--------------------------------

### Get Git Configuration Value

Source: https://github.com/git/htmldocs/blob/gh-pages/git-config.html

This command retrieves the value of a specific configuration key. For example, to get the value of core.filemode.

```bash
git config get core.filemode
```

--------------------------------

### Create Initial Files

Source: https://github.com/git/htmldocs/blob/gh-pages/gitcore-tutorial.adoc

Use 'echo' to create simple text files in your working directory. These files will be the starting point for Git tracking.

```bash
$ echo "Hello World" >hello
$ echo "Silly example" >example
```

--------------------------------

### Initialize a new Git project

Source: https://github.com/git/htmldocs/blob/gh-pages/gittutorial-2.html

Use this command to start a new project and initialize it with Git's version control system. This creates the necessary directory structure and configuration files for a Git repository.

```bash
mkdir test-project
cd test-project
git init
```

--------------------------------

### Install Apache on Debian

Source: https://github.com/git/htmldocs/blob/gh-pages/howto/setup-git-server-over-http.html

Installs the Apache web server package on Debian-based systems. Ensure Apache is configured to start by default.

```bash
apt-get install apache2
# To get apache2 by default started,
# edit /etc/default/apache2 and set NO_START=0
```

--------------------------------

### Start git-daemon Server

Source: https://github.com/git/htmldocs/blob/gh-pages/howto/use-git-daemon.adoc

Use this command to start the git-daemon server. Options like --reuseaddr help prevent binding issues, --verbose provides connection information, --base-path sets the root for exported repositories, and --export-all simplifies exporting without individual export files. Specify the repository path after '--'.

```bash
git daemon --reuseaddr --verbose --base-path=/home/gitte/git \
  --export-all -- /home/gitte/git/rule-the-world.git
```

--------------------------------

### Install Apache on Debian

Source: https://github.com/git/htmldocs/blob/gh-pages/howto/setup-git-server-over-http.adoc

Installs the Apache web server on Debian-based systems. Ensure Apache is configured to start by default by editing /etc/default/apache2.

```bash
apt-get install apache2
    To get apache2 by default started,
    edit /etc/default/apache2 and set NO_START=0
```

--------------------------------

### C: Thread Start and Data Logging

Source: https://github.com/git/htmldocs/blob/gh-pages/technical/api-trace2.html

This C code demonstrates starting a thread with a name and logging integer data, including repository, offset, and count. Ensure trace2 functions are correctly initialized.

```c
static void *preload_thread(void *_data)
{
        // start the per-thread clock and emit a message.
        trace2_thread_start("preload_thread");

        // report which chunk of the array this thread was assigned.
        trace2_data_intmax("index", the_repository, "offset", p->offset);
        trace2_data_intmax("index", the_repository, "count", nr);

        do {
            ...
        } while (--nr > 0);
        ...

        // report elapsed time taken by this thread.
        trace2_thread_exit();
        return NULL;
}
```

--------------------------------

### Invoke Custom Revision Setup

Source: https://github.com/git/htmldocs/blob/gh-pages/MyFirstObjectWalk.adoc

Call the custom setup function for 'struct rev_info' after initialization. This applies specific configurations like commit format and starting points for the walk.

```c
final_rev_info_setup(&rev);
```

--------------------------------

### Initialize New Git Repository

Source: https://github.com/git/htmldocs/blob/gh-pages/git-init.html

Use these commands to start a new Git repository for an existing project. Ensure you are in the project's root directory.

```bash
cd /path/to/my/codebase
git init      **(1)**
git add .     **(2)**
git commit    **(3)**
```

--------------------------------

### URL Rewriting Configuration

Source: https://github.com/git/htmldocs/blob/gh-pages/git-clone.html

Configure Git to rewrite URLs based on a pattern. This example rewrites URLs starting with 'host.xz:/path/to/' or 'work:' to 'git://git.host.xz/'.

```gitconfig
[url "git://git.host.xz/"]
        insteadOf = host.xz:/path/to/
        insteadOf = work:
```

--------------------------------

### Initialize a new Git repository and commit initial files

Source: https://github.com/git/htmldocs/blob/gh-pages/giteveryday.adoc

Use `git init` to create a new repository. `git add .` stages all files, and `git commit` records the changes. `git tag` marks a specific point in history.

```bash
$ tar zxf frotz.tar.gz
$ cd frotz
$ git init
$ git add .
$ git commit -m "import of frotz source tree."
$ git tag v2.43
```

--------------------------------

### Configure Git Credential Helper with Shell Snippet

Source: https://github.com/git/htmldocs/blob/gh-pages/gitcredentials.html

Specify a custom shell snippet as the credential helper. This example defines a function to handle the 'get' operation.

```gitconfig
[credential "https://example.com"]
        username = your_user
        helper = "!f() { test \"$1\" = get && echo \"password=$(cat $HOME/.secret)\"; }; f"
```

--------------------------------

### Configure Git Daemon as Inetd Server

Source: https://github.com/git/htmldocs/blob/gh-pages/git-daemon.html

Set up the git daemon to run as an inetd service. This example shows how to serve repositories from specific directories and enables verbose output.

```bash
git daemon --inetd --verbose --export-all /pub/foo /pub/bar
```

--------------------------------

### Display a Git logical variable

Source: https://github.com/git/htmldocs/blob/gh-pages/git-var.adoc

Use this command to retrieve the value of a specific Git logical variable. For example, to get the author's identification string.

```bash
git var GIT_AUTHOR_IDENT
```

--------------------------------

### Get URL-Specific Boolean Configuration Value

Source: https://github.com/git/htmldocs/blob/gh-pages/git-config.html

This command retrieves a boolean configuration value for a specific URL. It checks if sslVerify is true for a good example URL.

```bash
git config get --type=bool --url=https://good.example.com http.sslverify
```

--------------------------------

### Basic Test File Header

Source: https://github.com/git/htmldocs/blob/gh-pages/MyFirstContribution.html

Start your test script with this header, including the test description. Ensure `test-lib.sh` is sourced for test utilities.

```shell
#!/bin/sh

test_description='git-psuh test

This test runs git-psuh and makes sure it does not crash.'

. ./test-lib.sh
```

--------------------------------

### Get URL-Specific Boolean Configuration Value (False)

Source: https://github.com/git/htmldocs/blob/gh-pages/git-config.html

This command retrieves a boolean configuration value for a specific URL. It checks if sslVerify is false for a weak example URL.

```bash
git config get --type=bool --url=https://weak.example.com http.sslverify
```

--------------------------------

### Create and Initialize Bare Git Repository

Source: https://github.com/git/htmldocs/blob/gh-pages/howto/setup-git-server-over-http.adoc

Creates a directory for the Git repository under Apache's DocumentRoot and initializes it as a bare repository. Ensure the directory is writable by the web server user.

```bash
cd /usr/local/apache2/htdocs
    $ mkdir my-new-repo.git

  On Debian:

    $ cd /var/www
    $ mkdir my-new-repo.git
```

```bash
cd my-new-repo.git
    $ git --bare init
```

--------------------------------

### Skip 'doc*' directory for every fetch

Source: https://github.com/git/htmldocs/blob/gh-pages/git-svn.adoc

Use the --ignore-paths option to skip directories matching a Perl regular expression during fetches. This example skips any path starting with 'doc'.

```bash
--ignore-paths="^doc"
```

--------------------------------

### Setup Revision Info for One-Line Log

Source: https://github.com/git/htmldocs/blob/gh-pages/MyFirstObjectWalk.html

Configures `rev_info` to mimic `git log --oneline` format and sets HEAD as the starting point for the object walk. This helper function is called after `repo_init_revisions`.

```c
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);
}
```

--------------------------------

### Initialize and Commit to Git

Source: https://github.com/git/htmldocs/blob/gh-pages/gittutorial-2.html

Basic Git commands to initialize a repository, add a file, and make an initial commit. The output shows the commit hash and file status.

```bash
$ echo 'hello world' > file.txt
$ git add .
$ git commit -a -m "initial commit"
```

```bash
$ echo 'hello world!' >file.txt
$ git commit -a -m "add emphasis"
```

--------------------------------

### Create Initial Files for Git

Source: https://github.com/git/htmldocs/blob/gh-pages/gitcore-tutorial.html

Create simple text files in your working directory that will be added to the Git repository. These files serve as the initial content for your project.

```bash
echo "Hello World" >hello
echo "Silly example" >example
```

--------------------------------

### Interpreting Normal Trace2 Log Output

Source: https://github.com/git/htmldocs/blob/gh-pages/technical/api-trace2.html

Example of the content of a normal Trace2 log file. It shows the start and end of commands, child processes, and their execution times. This helps in diagnosing performance bottlenecks.

```log
version 2.20.1.vfs.1.1.47.g534dbe1ad1
start git fetch origin
worktree /Users/jeffhost/work/gfw
cmd_name fetch (fetch)
child_start[0] ssh git@github.com ...
child_start[1] git index-pack ...
... (Trace2 events from child processes omitted)
child_exit[1] pid:14707 code:0 elapsed:0.076353
child_exit[0] pid:14706 code:0 elapsed:4.931869
child_start[2] git rev-list ...
... (Trace2 events from child process omitted)
child_exit[2] pid:14708 code:0 elapsed:0.110605
child_start[3] git gc --auto
... (Trace2 events from child process omitted)
child_exit[3] pid:14709 code:0 elapsed:0.006240
exit elapsed:5.198503 code:0
atexit elapsed:5.198541 code:0
```

--------------------------------

### Display Git Command Usage (-h)

Source: https://github.com/git/htmldocs/blob/gh-pages/gitcli.html

Use the -h option to display a pretty-printed usage guide for a Git command. This is a standard way to get help for any command supporting the enhanced option parser.

```bash
git describe -h
```

--------------------------------

### Example Gitweb Repository URL Mapping

Source: https://github.com/git/htmldocs/blob/gh-pages/gitweb.conf.adoc

Illustrates how a configured $projectroot variable maps a web URL to a filesystem path. If $projectroot is '/srv/git', then URLs like 'http://git.example.com/gitweb.cgi?p=foo/bar.git' or its path_info equivalent map to '/srv/git/foo/bar.git' on the filesystem.

```http
http://git.example.com/gitweb.cgi?p=foo/bar.git
```

```http
http://git.example.com/gitweb.cgi/foo/bar.git
```

--------------------------------

### Initialize and Set Up a Bare Shared Git Repository

Source: https://github.com/git/htmldocs/blob/gh-pages/gitcvs-migration.adoc

Create a new bare Git repository (without a working tree) suitable for sharing. This command initializes the repository and sets it up to be shared among team members.

```bash
mkdir /pub/my-repo.git
cd /pub/my-repo.git
git --bare init --shared
git --bare fetch /home/alice/myproject master:master
```

--------------------------------

### Interpreting Performance Trace2 Log Output

Source: https://github.com/git/htmldocs/blob/gh-pages/technical/api-trace2.html

Example of a performance Trace2 log file. It shows detailed timing for various events, including region entries and exits, with elapsed times relative to the start of the process or nesting level.

```log
d0 | main                     | version      |     |           |           |            | 2.20.1.160.g5676107ecd.dirty
d0 | main                     | start        |     |  0.001173 |           |            | git status
d0 | main                     | def_repo     | r1  |           |           |            | worktree:/Users/jeffhost/work/gfw
d0 | main                     | cmd_name     |     |           |           |            | status (status)
...
d0 | main                     | region_enter | r1  |  0.010988 |           | status     | label:worktrees
d0 | main                     | region_leave | r1  |  0.011236 |  0.000248 | status     | label:worktrees
d0 | main                     | region_enter | r1  |  0.011260 |           | status     | label:index
d0 | main                     | region_leave | r1  |  0.012542 |  0.001282 | status     | label:index
d0 | main                     | region_enter | r1  |  0.012568 |           | status     | label:untracked
d0 | main                     | region_leave | r1  |  0.027149 |  0.014581 | status     | label:untracked
d0 | main                     | region_enter | r1  |  0.027411 |           | status     | label:print
d0 | main                     | region_leave | r1  |  0.028741 |  0.001330 | status     | label:print
d0 | main                     | exit         |     |  0.028778 |           |            | code:0
d0 | main                     | atexit       |     |  0.028809 |           |            | code:0
```

--------------------------------

### Automated Bisection Script Example

Source: https://github.com/git/htmldocs/blob/gh-pages/git-bisect-lk2009.adoc

This example illustrates a fully automated bootup-hang bisection script using 'git-bisect run'. It automatically builds and boots kernels, detecting failures via serial logs or timeouts.

```bash
i have a fully automated bootup-hang bisection script. It is based on
"git-bisect run". I run the script, it builds and boots kernels fully
automatically, and when the bootup fails (the script notices that via
the serial log, which it continuously watches - or via a timeout, if
the system does not come up within 10 minutes it's a "bad" kernel),
the script raises my attention via a beep and i power cycle the test
box. (yeah, i should make use of a managed power outlet to 100%
automate it)
```

--------------------------------

### Resolve Git Path with rev-parse

Source: https://github.com/git/htmldocs/blob/gh-pages/git-worktree.html

Use `git rev-parse --git-path` to get the final path within the Git repository, respecting environment variables like `$GIT_DIR` and `$GIT_COMMON_DIR`. This is crucial when directly accessing files within `$GIT_DIR` to ensure correctness across different worktree setups.

```bash
git rev-parse --git-path HEAD
```

```bash
git rev-parse --git-path refs/heads/master
```

--------------------------------

### git maintenance start

Source: https://github.com/git/htmldocs/blob/gh-pages/git-maintenance.html

Starts background maintenance for the current repository.

```APIDOC
## git maintenance start

### Description
Start running maintenance on the current repository. This performs the same config updates as the `register` subcommand, then updates the background scheduler to run `git maintenance run --scheduled` on an hourly basis.

### Method
CLI Command

### Endpoint
N/A

### Parameters
N/A

### Request Body
N/A

### Response
N/A

#### Success Response (0)
Indicates that background maintenance has been started.

#### Response Example
N/A
```

--------------------------------

### Example Git Configuration for Submodule Activation

Source: https://github.com/git/htmldocs/blob/gh-pages/gitsubmodules.adoc

Illustrates how to configure submodule activation using 'active' and 'url' settings, including precedence rules and pathspec filtering.

```ini
[submodule "foo"]
  active = false
  url = https://example.org/foo
[submodule "bar"]
  active = true
  url = https://example.org/bar
[submodule "baz"]
  url = https://example.org/baz
```

```ini
[submodule "foo"]
  active = true
  url = https://example.org/foo
[submodule "bar"]
  url = https://example.org/bar
[submodule "baz"]
  url = https://example.org/baz
[submodule "bob"]
  ignore = true
[submodule]
  active = b*
  active = :(exclude) baz
```

--------------------------------

### git maintenance start

Source: https://github.com/git/htmldocs/blob/gh-pages/git-maintenance.html

Starts the Git maintenance scheduler. This command allows for the configuration of the scheduler.

```APIDOC
## git maintenance start

### Description
Starts the Git maintenance scheduler.

### Method
`git maintenance`

### Endpoint
`start [--scheduler=<scheduler>]`

### Parameters
#### Query Parameters
- **scheduler** (string) - Optional - Specifies the scheduler to use.
```