### Git Subrepo Usage

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics

Displays the basic usage syntax for the git-subrepo command, outlining its structure for commands and arguments.

```shell
$ git subrepo
usage: git subrepo <command> <arguments> <options>
```

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

### Initialize Shared Repository

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics

Initializes a new Git repository for shared files and commits the initial state of the shared files 'bar' and 'foo'.

```shell
$ cd /tmp/shared
$ git init
Initialized empty Git repository in /tmp/shared/.git/
$ git add .
$ git commit -m "Initial revision of our shared code"
[master (root-commit) 1c1c881] Initial revision of our shared code
 2 files changed, 2 insertions(+)
 create mode 100644 bar
 create mode 100644 foo
```

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

### Clone Project Repository

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics

Clones a bare Git repository named 'project_bare' into a local directory named 'project', which contains an initial file 'alpha'.

```shell
$ cd /tmp/
$ git clone project_bare project
Cloning into 'project'...
done.
```

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

### Git Merge Workflow Example 1

Source: https://github.com/ingydotnet/git-subrepo/wiki/Workflows

Demonstrates a basic Git merge operation between a 'master' and 'topic' branch, showing the evolution of commits and the resulting merge commit.

```shell
    D - E topic
  /      
A - B - C master

$ git checkout master
$ git merge topic

    D - E topic
  /       \
A - B - C - F master
```

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

### Git Subrepo Pull Workflow Example 2

Source: https://github.com/ingydotnet/git-subrepo/wiki/Workflows

Shows how git-subrepo handles subsequent pulls when local changes are not pushed, demonstrating the continued reliance on content hash ancestry for rebasing.

```shell
#10,a - #20,b - #30,c - #70,h subrepo
#10,a - #20,b - #30,c - #70,h  subrepo/fetch
#41,a - #51,d - #61,e - #64,f - #81,g project/subrepo/branch
#40,A - #50,D - #60,E - #63,F - #80,G project
```

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

### Initialize and Push Subrepo to New Repository

Source: https://github.com/ingydotnet/git-subrepo/wiki/FAQ

This snippet demonstrates how to initialize a subdirectory as a git-subrepo and push it to a new remote repository. It covers the initial setup and subsequent push operation for shared code management.

```bash
cd <old-project>
git subrepo init <subdir> -r <remote> [-b <branch>]
git subrepo push <subdir>
```

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

### Modify Project and Subrepository

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics

Demonstrates making changes within the project (adding 'delta') and modifying files within the sub-repository ('shared/foo'), then committing these changes locally.

```shell
$ touch delta
$ echo 123 >> shared/foo 
$ git add .
$ git commit -m "Add delta, edit shared/foo"
[master d8b0e12] Add delta, edit shared/foo
 2 files changed, 1 insertion(+)
 create mode 100644 delta
$ echo abc >> alpha 
$ git add .
$ git commit -m "Edit alpha"
[master 3b068bd] Edit alpha
 1 file changed, 1 insertion(+)
$ touch shared/fie
$ git add .
$ git commit -m "Add shared/fie"
[master ed859fe] Add shared/fie
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 shared/fie
$ git log --oneline
ed859fe (HEAD -> master) Add shared/fie
3b068bd Edit alpha
d8b0e12 Add delta, edit shared/foo
cadfff1 git subrepo clone /tmp/shared
68442e4 New alpha
```

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

### Clone Subrepository into Project

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics

Clones the shared repository into the project repository as a sub-repository named 'shared'. It then shows the updated file list and commit history.

```shell
$ cd /tmp/project
$ git subrepo clone /tmp/shared
Subrepo '/tmp/shared' (master) cloned into 'shared'.
$ git ls-files
alpha
shared/.gitrepo
shared/bar
shared/foo
$ git log --oneline
cadfff1 (HEAD -> master) git subrepo clone /tmp/shared
68442e4 (origin/master) New alpha
```

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

### Git Merge Workflow Example 2

Source: https://github.com/ingydotnet/git-subrepo/wiki/Workflows

Illustrates a subsequent Git merge operation, highlighting how Git uses previously created parent connections to determine the common ancestor for the merge.

```shell
    D - E - G - H topic
  /       \
A - B - C - F - I master

$ git checkout master
$ git merge topic

    D - E - G - H topic
  /       \       \
A - B - C - F - I - J master
```

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

### View .gitrepo Configuration

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics

Displays the content of the .gitrepo file, which stores essential configuration information for the sub-repository, such as its remote, branch, commit, and integration method.

```shell
$ cat shared/.gitrepo 
; DO NOT EDIT (unless you know what you are doing)
;
; This subdirectory is a git "subrepo", and this file is maintained by the
; git-subrepo command. See https://github.com/ingydotnet/git-subrepo#readme
;
[subrepo]
        remote = /tmp/shared
        branch = master
        commit = 1c1c881f2232f5f80e6c67a4d31d28ed1f1d90cf
        parent = 68442e465e2ea3e9ece0718234556f1b82628d79
        method = merge
        cmdver = 0.4.0
```

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

### Git Subrepo Pull Workflow Example 1

Source: https://github.com/ingydotnet/git-subrepo/wiki/Workflows

Explains git-subrepo's approach to pulling changes by relying on content tree hashes to find common ancestors, rather than explicit parent connections.

```shell
#10,a - #20,b - #30,c subrepo
#10,a - #20,b - #30,c subrepo/fetch
#41,a - #51,d - #61,e project/subrepo/branch
#40,A - #50,D - #60,E project

#10,a - #20,b - #30,c subrepo
#10,a - #20,b - #30,c - #52,d' - #62,e' subrepo/fetch
#41,a - #51,d - #61,e project/subrepo/branch
#40,A - #50,D - #60,E - #63,E' project
```

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

### Compare Directories with Diff

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics

Compares the contents of two directories, highlighting differences. This is useful for understanding changes between a project's view of shared code and the actual shared repository.

```shell
$ diff /tmp/project/shared/ /tmp/shared/
Only in /tmp/shared/: .git
Only in /tmp/project/shared/: .gitrepo
```

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

### Push Project Changes

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics

Pushes the local changes made to the project repository to the remote origin. This updates the main project but does not automatically sync changes back to the sub-repository.

```shell
$ git push
Counting objects: 17, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (12/12), done.
Writing objects: 100% (17/17), 1.66 KiB | 0 bytes/s, done.
Total 17 (delta 3), reused 0 (delta 0)
To /tmp/project_bare
   68442e4..ed859fe  master -> master
```

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

### Add Changes to Shared Subrepository

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics

Adds new files ('idle') and modifies existing files ('bar') within the shared sub-repository, commits these changes, and switches to a new branch to prepare for pushing.

```shell
$ cd /tmp/shared
$ touch idle
$ git add .
$ git commit -m "Add idle"
[master 6702317] Add idle
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 idle
$ echo 123545 >> bar 
$ git add .
$ git commit -m "Edit bar"
[master 2cb9f79] Edit bar
 1 file changed, 1 insertion(+)
$ git log --oneline
2cb9f79 (HEAD -> master) Edit bar
6702317 Add idle
1c1c881 Initial revision of our shared code
$ git checkout -b other       # We need to step away from master if we want others to push changes here
Switched to a new branch 'other'
```

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

### View Git Log Graph (Shared Repo)

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics

Displays the commit history of the shared repository in a graphical, one-line format. This helps visualize the evolution of the shared code independently.

```shell
$ cd /tmp/shared
$ git log --oneline --graph
*   c6b4908 (HEAD -> master) git subrepo pull (merge) shared   # 
|\  
| * 2cb9f79 (other) Edit bar              # Subrepo change
| * 6702317 Add idle                      # Subrepo change
* | 2ecfb0b Add shared/fie                # Subrepo version of ed859fe
* | 8ab2ea9 Add delta, edit shared/foo    # Subrepo version of d8b0e12
|/  
* 1c1c881 Initial revision of our shared code 
```

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

### Pull Subrepository Updates

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics

Pulls the latest changes from the shared sub-repository into the project repository. This command fetches changes from the sub-repository's remote and merges them into the project's view of the sub-repository.

```shell
$ cd /tmp/project
$ git subrepo pull shared
Subrepo 'shared' pulled from '/tmp/shared' (master).
$ git log --oneline
d2bbc1e (HEAD -> master) git subrepo pull (merge) shared
ed859fe (origin/master) Add shared/fie
3b068bd Edit alpha
d8b0e12 Add delta, edit shared/foo
cadfff1 git subrepo clone /tmp/shared
68442e4 New alpha
$ git ls-files
alpha
delta
shared/.gitrepo
shared/bar
shared/fie
shared/foo
shared/idle
```

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

### Push Subrepository Changes

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics

Pushes local changes made within the project's sub-repository back to the sub-repository's remote origin. This synchronizes the sub-repository's content with the changes made via the project.

```shell
$ cd /tmp/project
$ git subrepo push shared
Subrepo 'shared' pushed to '/tmp/shared' (master).
$ cd /tmp/shared
$ git checkout master     # We need to get back to master to see the changes we pushed
Switched to branch 'master'
$ git log --oneline --graph
*   c6b4908 (HEAD -> master) git subrepo pull (merge) shared
|  
| * 2cb9f79 (other) Edit bar
| * 6702317 Add idle
* | 2ecfb0b Add shared/fie
* | 8ab2ea9 Add delta, edit shared/foo
|/

```

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

### View Git Log Graph (Project Repo)

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics

Displays the commit history of the main project repository, including subrepo operations, in a graphical, one-line format. This shows how subrepo changes are integrated and managed within the project.

```shell
$ cd /tmp/project
$ git log --oneline --graph
* 15b09d7 (HEAD -> master) git subrepo push shared  # Update .gitrepo file
* d2bbc1e git subrepo pull (merge) shared # Merge local change with 2cb9f79 and 6702317 from subrepo
* ed859fe (origin/master) Add shared/fie  # Only change subrepo, visible in subrepo
* 3b068bd Edit alpha                      # Only changed project, not visible in subrepo    
* d8b0e12 Add delta, edit shared/foo      # Change both project and subrepo, visible in subrepo
* cadfff1 git subrepo clone /tmp/shared   # Clone in state from 1c1c881
* 68442e4 New alpha                       # Start repo
```

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

### Change Subrepo Tracking Branch

Source: https://github.com/ingydotnet/git-subrepo/wiki/FAQ

This snippet explains how to change the tracking branch for an existing git-subrepo, for example, to switch to a different tag or branch. The --force option is used to re-clone the subrepo with the new tracking configuration.

```bash
git subrepo clone --force -b <new_remote_branch> <remote>
```

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

### Initialize Git Repository

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics0.3

Demonstrates the standard Git commands to initialize a new Git repository, add files, and create an initial commit. This is often a prerequisite for setting up shared code or subrepositories.

```bash
cd /tmp/shared
git init
git add .
git commit -m "Initial revision of our shared code"
```

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

### Clone Project Repository

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics0.3

Shows how to clone an existing Git repository. This command is used to create a local copy of a remote or local repository, typically to work on a project.

```bash
cd /tmp
git clone /tmp/project_bare/ project
```

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

### Git Subrepo vs. Subtree vs. Submodule Comparison

Source: https://github.com/ingydotnet/git-subrepo/wiki/FAQ

This entry compares git-subrepo with git subtree and git submodule, highlighting differences in initialization, management, and history handling. It notes that git-subrepo aims to simplify common code management and updates.

```APIDOC
Git Subrepo vs. Subtree vs. Submodule:

Comparison of methods for managing shared code across Git repositories.

Initialization from existing repo/subdir:
  - git-subrepo: `git subrepo init`
  - subtree: `git subtree split`
  - submodule: `git clone`, `git filter branch`, and other commands

Putting separated common code into a new project:
  - git-subrepo: `git subrepo clone`
  - subtree: `git subtree add`
  - submodule: `git submodule add`

Notes:
- git-subrepo aims for simpler updates and pushes with a single command (`git subrepo push`).
- git-subtree and git-submodule procedures can be more complex for updates and management.
- git-stree has been deprecated in favor of git-subrepo.
- git-subrepo is considered to be in beta and may have unsolved problems.
```

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

### Compare Project and Shared Directories

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics0.3

Demonstrates how to use the 'diff' command to compare the contents of a project's subrepository directory with the actual shared repository directory, highlighting differences like the presence of .git and .gitrepo files.

```shell
$ diff /tmp/project/shared/ /tmp/shared/
Only in /tmp/shared/: .git
Only in /tmp/project/shared/: .gitrepo
```

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

### Git Subrepo Initialization Performance

Source: https://github.com/ingydotnet/git-subrepo/wiki/FAQ

Details the performance of `git subrepo init` for large repositories. It notes that initialization can take significant time, with potential for improvement through options like squashing history.

```git
git subrepo init
```

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

### git-subrepo init command

Source: https://github.com/ingydotnet/git-subrepo/wiki/Command-summary-test-for-issue-328

Turns an existing subdirectory into a subrepo, configuring it to be managed by git-subrepo. It allows setting the remote and branch for the subrepo.

```APIDOC
git-subrepo init
  Turn an existing subdirectory into a subrepo.

  Parameters:
    subdir: Target sub directory.
    [--remote]: Set .gitrepo subrepo.remote.
    [--branch]: Set .gitrepo subrepo.branch.

  Conditions:
    START: Nothing
    END: Subrepo inside sub directory.
    ERROR: No sub directory exists. Action: Create and add a subdirectory.
    ERROR: Sub directory is not part of the repo. Action: Add subdirectory to repo with git add.
```

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

### Clone Subrepository into Project

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics0.3

Illustrates the core git-subrepo command to clone an external repository into a subdirectory of the current project. This integrates the external repository's content and history as a subrepository.

```bash
cd /tmp/project
git subrepo clone /tmp/shared/ shared
```

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

### Git Subrepo Command Usage

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics0.3

Displays the general usage syntax for the git-subrepo command-line tool. It outlines the structure for invoking subrepo commands with arguments and options.

```APIDOC
git subrepo <command> <arguments> <options>
...
```

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

### Git Subrepo Push/Pull Performance

Source: https://github.com/ingydotnet/git-subrepo/wiki/FAQ

Explains the performance characteristics of pushing and pulling subrepositories, highlighting the impact of repository size and commit history. Mentions a tree-hash common-ancestor algorithm and its complexity.

```git
git subrepo push
git subrepo pull
```

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

### Clone Subrepo into New Project

Source: https://github.com/ingydotnet/git-subrepo/wiki/FAQ

This snippet shows how to clone an existing git-subrepo into a new project. It specifies the remote repository and optionally a subdirectory within the new project where the subrepo will be placed.

```bash
cd <new-project>
git subrepo clone <remote> [<subdir>] [-b <branch>]
```

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

### Git Subrepo Method Option for Clone and Init

Source: https://github.com/ingydotnet/git-subrepo/wiki/0.4.0-Release-Plan

Describes the --method option for the git-subrepo clone and init commands. This option enables users to define the default merge strategy (merge, rebase, or force) directly within the .gitrepo configuration file during repository initialization or cloning.

```APIDOC
Git Subrepo Method Option for Clone and Init:

  clone --method <method>
    - Initializes a new .gitrepo file or updates an existing one with the specified method (merge|rebase|force) for clone operations.
    - Example: `git subrepo clone --method rebase <repository_url>`

  init --method <method>
    - Adds or updates the 'method' (merge|rebase|force) in the .gitrepo file for the clone and init commands.
    - Example: `git subrepo init --method force` will set the default method for future clone/init operations to force.
```

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

### Initialize Subrepo to Own Branch in Original Repository

Source: https://github.com/ingydotnet/git-subrepo/wiki/FAQ

This snippet illustrates initializing a subdirectory as a git-subrepo and placing it onto its own branch within the original repository. This method keeps the subrepo history within the same Git project but on a dedicated branch.

```bash
cd <old-project>
git subrepo init <subdir>
git subrepo branch <subdir>
git branch
* master
  subrepo/<subdir>    <--This is the branch containing <subdir> and all its history
```

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

### Git Subrepo Pull Command Sequence

Source: https://github.com/ingydotnet/git-subrepo/wiki/Advanced0.3

Demonstrates the sequence of git commands used to perform a subrepo pull operation, illustrating the state of shared and project trees.

```shell
#Commit hash,Tree hash
#Capital letters are project tree hash, letters are shared tree hash
#shared:   #1,a - #2,b - #3,c      
#project:  #4,A - #5,D

git subrepo fetch => shared/fetch
# shared/fetch: #1,a - #2,b - #3,c
git subrepo branch => shared/branch
# shared/branch: #41,a - #51,d
git subrepo mergebase shared/fetch shared/branch => new_parent: #1, old_parent: #41
git rebase --onto new_parent old_parent shared/branch
# shared/fetch: #1,a - #2,b - #3,c
# shared/branch: #1,a - #51,d
git rebase shared/fetch shared/branch
# shared/fetch: #1,a - #2,b - #3,c - #52,d'
git subrepo commit
# project: #4,A - #5,D - #6,D'
```

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

### Git Subrepo Tools

Source: https://github.com/ingydotnet/git-subrepo/wiki/Advanced0.3

Provides an overview of the core command-line tools offered by git-subrepo for managing sub-repositories. These commands facilitate operations like finding common ancestors, fetching sub-repositories, creating branches, and committing changes.

```APIDOC
git subrepo merge-base
  Description: Takes two branches and compares their tree hashes to find the first common ancestor based on tree hashes. It returns the first unique tree hash found on both branches.
  Usage: git subrepo merge-base <branch1> <branch2>

git subrepo fetch
  Description: Fetches the sub-repository content into the current repository.
  Usage: git subrepo fetch

git subrepo branch
  Description: Performs filter-branch operations on the local repository to create a new branch representing the local version of the sub-repository.
  Usage: git subrepo branch

git subrepo commit
  Description: Commits the content of a branch to the local repository and updates the .gitrepo file.
  Usage: git subrepo commit
```

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

### Manage Subrepo Branches

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics0.3

Illustrates how to switch branches within the subrepository context. It shows checking out a new branch in the shared subrepo to make changes that can be pushed later.

```bash
cd /tmp/shared
git checkout -b other
```

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

### Git Subrepo Testing and Documentation Updates

Source: https://github.com/ingydotnet/git-subrepo/wiki/0.4.0-Release-Plan

Highlights the need for comprehensive tests for new features and updates to existing documentation. This ensures the stability and usability of the git-subrepo project.

```APIDOC
Git Subrepo Development Tasks:

  - Add tests for new functionality.
    - Implement unit and integration tests to cover recently added features and bug fixes.

  - Update documentation.
    - Ensure all new features, options, and behaviors are clearly documented.
    - Reference external resources like provided Gists for potential documentation improvements.
```

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

### Update Subrepository (Pull)

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics0.3

Explains how to fetch and apply changes from the subrepository's remote to the local subrepository within the project. This command synchronizes the subrepo content with its upstream.

```bash
cd /tmp/project
git subrepo pull shared
```

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

### Subrepo Configuration File (.gitrepo)

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics0.3

Details the content of the .gitrepo file, which stores essential metadata for a git-subrepo. This includes the remote URL, branch, commit hash, parent commit, and command version.

```ini
[subrepo]
        remote = ../shared
        branch = master
        commit = 58e908c601bfb346fad0bd639d78415474db0ffd
        parent = b228b44453645162664ccaea8a4ab210ec33df66
        cmdver = 0.3.0
```

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

### Push Project Changes

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics0.3

Shows how to push local commits from the main project repository to its remote. This action synchronizes the project's history, including the subrepo commits, with the remote repository.

```bash
git push
```

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

### Push Subrepository Changes

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics0.3

Demonstrates how to push changes made within the project's subrepository back to the subrepository's own remote. This command synchronizes the subrepo's local changes upstream.

```bash
cd /tmp/project
git subrepo push shared
```

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

### Commit Changes in Project and Subrepo

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics0.3

Demonstrates making local changes within the project, including modifications to files within the subrepository, staging them, and committing them. This process updates the project's history with subrepo changes.

```bash
touch delta
echo "123" >> shared/foo
git add .
git commit -m "Add delta, edit shared/foo"

echo "abc" >> alpha
echo "def" >> beta
git add .
git commit -m "Edit alpha, beta"

touch shared/fie
git add .
git commit -m "Add shared/fie"
```

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

### Git Subrepo Pull Command Options

Source: https://github.com/ingydotnet/git-subrepo/wiki/0.4.0-Release-Plan

Details the required options for the git-subrepo pull command. It specifies that a pull operation must be accompanied by a merge strategy, either explicitly via command-line flags or implicitly through a configured .gitrepo method.

```APIDOC
Git Subrepo Pull Command:

  pull
    - Requires --merge, --rebase, --force, or a .gitrepo 'method' to be specified.
    - Ensures explicit user intent for handling divergent histories.

  pull --merge
    - Merges changes from the remote repository.

  pull --rebase
    - Rebases local changes onto the remote changes.

  pull --force
    - Forces the pull operation, potentially overwriting local changes.

  pull (using .gitrepo method)
    - If a 'method' is defined in the .gitrepo file (e.g., merge, rebase, force), it will be used by default.
    - Example .gitrepo entry: method = merge
```

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

### Compare Git Logs of Project and Shared Repos

Source: https://github.com/ingydotnet/git-subrepo/wiki/Basics0.3

Illustrates how to compare the commit histories of a main project and its associated shared subrepository using 'git log'. This helps in understanding how commits from the shared repository are integrated into the project, including squashing and ignoring irrelevant changes.

```shell
$ cd /tmp/project
$ git log --pretty=oneline
8eab0448436729de89d659f413ebedcdf34f2b84 git subrepo pull shared             #1.1 includes 2.3, 2.4
0468d4081300b8c2bce657c8145c7a353decbc85 Add shared/fie                      #1.2 same as 2.1
e58906879f85bee65b7e448a4034b60ef789e428 Edit alpha, beta                    #1.3 no change in shared, ignored in 2
c9b9003621c75dca6636a1ed5c8ad5663b255016 Add delta, edit shared/foo          #1.4 same as 2.2
0a6dceb7f0d97b690db5338d5a4d6016ca9548f6 git subrepo clone ../shared shared
b228b44453645162664ccaea8a4ab210ec33df66 Initial project commit

$ cd /tmp/shared
$ git log --pretty=oneline
d7721ef4afad14e549b5714b49c18a8576b3f03e Add shared/fie                      #2.1 same as 1.2
76edeecc13cf16bdb3fbe09225c8fd48452dd3fd Add delta, edit shared/foo          #2.2 same as 1.4
4b4ed1f3963771f6becf7a035e2917208457cf7e Edit bar                            #2.3 included in 1.1
d8246fa3d1df2f9a0fef2b2b486003a41c2d6de4 Add idle                            #2.4 included in 1.1
58e908c601bfb346fad0bd639d78415474db0ffd Initial revision of our shared code
```

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

### Git Log Commit and Tree Hashes (Project)

Source: https://github.com/ingydotnet/git-subrepo/wiki/Advanced0.3

Displays commit and tree hashes for the main project directory using git log. This is used to compare against sub-repository hashes after filtering.

```Shell
cd /tmp/project
 git log --pretty=format:%H:%T
8eab0448436729de89d659f413ebedcdf34f2b84:6206c803d1e110f75fd3352b288b2c34f46fe78a
0468d4081300b8c2bce657c8145c7a353decbc85:0924d8450f172023e4ebb9f85d46f04511e26201
e58906879f85bee65b7e448a4034b60ef789e428:910c1535c0503ce3165e45361ff756485ecaadf9
c9b9003621c75dca6636a1ed5c8ad5663b255016:a592bd78e25317811ed8f178c5f85b2fa241da07
0a6dceb7f0d97b690db5338d5a4d6016ca9548f6:1b36e06119b7378629cb947431d2fa279ec9a314
b228b44453645162664ccaea8a4ab210ec33df66:c8b86188bde90614f60f3953679026fe651300ab
```

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

### Clone Subrepo from Original Repository's Branch

Source: https://github.com/ingydotnet/git-subrepo/wiki/FAQ

This snippet demonstrates cloning a git-subrepo that resides on a specific branch within the original repository. It requires specifying the original project path and the dedicated subrepo branch name.

```bash
cd <new-project>
git subrepo clone <old-project> [<subdir>] [-b 'subrepo/<subdir>']
```

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

### Updating Local .gitrepo with Force Clone

Source: https://github.com/ingydotnet/git-subrepo/wiki/FAQ

Provides a method to update a local `.gitrepo` file when it might be out of sync, particularly after a failed push or manual intervention. This involves performing a new clone operation with the `--force` flag.

```git
git clone --force <repository_url> <destination>
```

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

### Git Log Commit and Tree Hashes (Subrepo)

Source: https://github.com/ingydotnet/git-subrepo/wiki/Advanced0.3

Displays commit and tree hashes for a sub-repository directory using git log. This helps in comparing content similarity between different repository states.

```Shell
cd /tmp/shared
git log --pretty=format:%H:%T
d7721ef4afad14e549b5714b49c18a8576b3f03e:6115f88b566c079a4934fcbb1893ba6ea46d3760
76edeecc13cf16bdb3fbe09225c8fd48452dd3fd:a6ed13d8eee5f96a6f00b8f390dff09759c50188
4b4ed1f3963771f6becf7a035e2917208457cf7e:3d087d282c29528e1aa8fe9dffee65142845f903
d8246fa3d1df2f9a0fef2b2b486003a41c2d6de4:20d0cce11701bcab9a3ab4baf8e1ab6b845a2b34
58e908c601bfb346fad0bd639d78415474db0ffd:ea41dba10b54a794284e0be009a11f0ff3716a28
```

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

### Git Log After Filtering (Subrepo and Project)

Source: https://github.com/ingydotnet/git-subrepo/wiki/Advanced0.3

Displays git log hashes after applying filter-branch operations. This allows for direct comparison of tree hashes between the filtered project repository and the original sub-repository, identifying common states.

```Shell
cd /tmp/shared
git log --pretty=format:%H:%T
d7721ef4afad14e549b5714b49c18a8576b3f03e:6115f88b566c079a4934fcbb1893ba6ea46d3760   #1.1 = 2.1
76edeecc13cf16bdb3fbe09225c8fd48452dd3fd:a6ed13d8eee5f96a6f00b8f390dff09759c50188
4b4ed1f3963771f6becf7a035e2917208457cf7e:3d087d282c29528e1aa8fe9dffee65142845f903
d8246fa3d1df2f9a0fef2b2b486003a41c2d6de4:20d0cce11701bcab9a3ab4baf8e1ab6b845a2b34
58e908c601bfb346fad0bd639d78415474db0ffd:ea41dba10b54a794284e0be009a11f0ff3716a28   #1.2 = 2.2

cd /tmp/project
git log --pretty=format:%H:%T
c8dc7cbbeb5819ff8ab9876578267ff82da01769:6115f88b566c079a4934fcbb1893ba6ea46d3760   #2.1 = 1.1
fbc118f495e6142373028b9f11e5205cc9faebf0:36bf4b39b551393d28a9cceb2a018ff1879e4019
83ccd589cee354f475c863ec1a6bd61efed58305:b46188214de22570d0edee2a053970f5f3179caf
4acbf09e997c600b13b8436a2436dfc595d35981:ea41dba10b54a794284e0be009a11f0ff3716a28   #2.2 = 1.2
```

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

### Git Filter-Branch for Subdirectory and Cleanup

Source: https://github.com/ingydotnet/git-subrepo/wiki/Advanced0.3

Applies git filter-branch to isolate a subdirectory and remove the .gitrepo file from commits. This prepares the repository for comparing tree hashes between the main project and the sub-repository.

```Shell
cd /tmp/project
git filter-branch -f --subdirectory-filter shared
Rewrite 8eab0448436729de89d659f413ebedcdf34f2b84 (4/4) (0 seconds passed, remaining 0 predicted)    
Ref 'refs/heads/master' was rewritten
git filter-branch -f --prune-empty --tree-filter "rm -f .gitrepo"
Rewrite 943e80c38174e56ee6018b0e9a9df4c3e2b06484 (4/4) (0 seconds passed, remaining 0 predicted)    
Ref 'refs/heads/master' was rewritten
```

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

### Simple Git Subrepo Pull with Rebase

Source: https://github.com/ingydotnet/git-subrepo/blob/master/note/pull-dance.txt

This workflow demonstrates a straightforward method to pull changes from a git subrepository using the `--rebase` option. It's suitable for directly updating the subrepo with remote changes while maintaining a clean history.

```shell
( 
    git sr pull --rebase ext/bar
)
```

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

### Manual Rebase and Continue Workflow for Git Subrepos

Source: https://github.com/ingydotnet/git-subrepo/blob/master/note/pull-dance.txt

This method involves manually rebasing the subrepository against a specific branch after pulling changes. It provides more control over the rebase process and is followed by testing and continuing the operation, suitable for complex integration scenarios.

```shell
( 
    git sr checkout ext/bar
    git rebase subrepo/remote/ext/bar
    make test
    git sr pull --continue
)
```

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

### Git Subrepo Pull and Continue Rebase Workflow

Source: https://github.com/ingydotnet/git-subrepo/blob/master/note/pull-dance.txt

This workflow outlines a process for pulling changes, rebasing, testing, and then continuing the rebase operation. It's useful when conflicts or issues arise during the rebase that require manual intervention or testing before completion.

```shell
( 
    git sr checkout ext/bar --rebase
    make test
    git sr pull --continue
)
```

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

### Git Subrepo Update Option for Pull

Source: https://github.com/ingydotnet/git-subrepo/wiki/0.4.0-Release-Plan

Introduces the --update option for the git-subrepo pull command. This option allows users to specify a default merge strategy that will be stored in the .gitrepo configuration file for future pull operations.

```APIDOC
Git Subrepo Update Option for Pull:

  pull --update <method>
    - Adds or updates the 'method' (merge|rebase|force) in the .gitrepo file for the pull command.
    - Example: `git subrepo pull --update merge` will set the default pull method to merge.
    - Subsequent `git subrepo pull` commands will use the configured method unless overridden.
```

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

### git-subrepo clone command

Source: https://github.com/ingydotnet/git-subrepo/wiki/Command-summary-test-for-issue-328

Clones a Git repository as a subrepo into a specified subdirectory within the current repository. It supports specifying an upstream branch and forcing the overwrite of existing subdirectories.

```APIDOC
git-subrepo clone
  Clones repo as a subrepo in a sub directory in your repository

  Parameters:
    repository: Repository to clone
    [subdir]: Sub directory name, defaults to the directory part of the repository name.
    [--branch]: Upstream branch, defaults to the HEAD branch.
    [--force]: Overwrite existing sub directory.

  Conditions:
    START: Nothing
    END: Subrepo inside sub directory.
    ERROR: No default HEAD branch. Action: Use --branch or move HEAD to a valid branch in the target repository.
```

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

### Git Subrepo Push Command Behavior

Source: https://github.com/ingydotnet/git-subrepo/wiki/0.4.0-Release-Plan

Specifies the intended behavior for the git-subrepo push command. It mandates that a push operation should not automatically perform a pull, requiring users to explicitly manage updates before pushing.

```APIDOC
Git Subrepo Push Command Behavior:

  push
    - The push command should not automatically pull changes from the remote repository.
    - Users must explicitly perform a pull operation first if updates are needed before pushing.
    - This prevents unexpected merges or conflicts during the push process.
```

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

### git-subrepo pull command

Source: https://github.com/ingydotnet/git-subrepo/wiki/Command-summary-test-for-issue-328

Updates a subrepo subdirectory with the latest upstream changes. It supports pulling from all subrepos, specifying a branch, cleaning up worktrees, and handling force/squash scenarios.

```APIDOC
git-subrepo pull
  Update a subrepo sub directory with latest upstream changes.

  Parameters:
    subdir: Target sub directory.
    [--all]: Target all subrepos.
    [--branch]: Use this branch instead of subrepo.branch.
    [--clean]: Clean up previous branches worktree.
    [--force]: Ignore previous upstream HEAD.
    [--remote]: Use this remote instead of subrepo.remote.
    [--squash]: Ignore the subrepo.parent, squash commits in local branch.
    [--update]: Update .gitrepo subrepo.remote and subrepo.branch from --remote and --branch.

  Conditions:
    START: Clean subrepo.
    END: Subrepo synced with upstream.
    ERROR: Worktree already exists. Action: Use --clean.
    ERROR: Current subrepo HEAD is not part of upstream. Action: Use --force.
    ERROR: Current parent is not part of branch (rebase). Action: Use --squash.
```

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

### Git Subrepo Edit Bug

Source: https://github.com/ingydotnet/git-subrepo/wiki/0.4.0-Release-Plan

Notes a known bug related to the --edit option in the git-subrepo tool. The exact nature of the bug is not detailed, but it indicates an area requiring investigation and correction.

```APIDOC
Git Subrepo Edit Bug:

  - Fix --edit bug.
    - This refers to an existing issue with the --edit functionality that needs to be addressed.
    - Further investigation is required to understand the specific problem and implement a fix.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.