git-subproject

#!/bin/bash
source "$( dirname $( readlink -e $0 ) )/lib/lib.sh"


#
# Constants
MY_BRANCH=$( git symbolic-ref --short HEAD )
STATE_FILE="$GIT_REPO/GIT_SUBPROJECT_CONTINUE"
PULL_MARKER="git-subproject-pull:"
PUSH_MARKER="git-subproject-push:"

#
# Input Variables (set in "stage 1 - read arguments" or "stage 2 - preparation")
IN_MODE=
IN_THEIR_BRANCH=
IN_MY_PREFIX=
IN_THEIR_PREFIX=
IN_BASE_PREFIX=
IN_FILTER=
IN_BASE_FILTER=
IN_FILTER_MODE="glob"
IN_MESSAGE=
IN_HISTORY_FORMAT="medium"
IN_MERGE_FILE_CONFLICT_STYLE=""
IN_MERGE_FILE_MODE=""
IN_IGNORE_ID=
IN_ALLOW_EMPTY=

#
# Context Variables

## Set in "stage 2 - preparation"
## Note: SOURCE and TARGET are relative to the merge direction where as MY and
##       THEIR always match the user input
##       during PULL/INIT: SOURCE - my branch   ; TARGET - their branch
##       during PUSH     : Source - their branch; TARGET - my branch
C_MARKER="$PULL_MARKER"   # Either $PULL_MARKER or $PUSH_MARKER - used to format
                          # commit message
C_SUBPROJECT_ID=          # Unique identifier for the current subproject
C_SOURCE_BRANCH_SPEC=     # Source branch (foreign branch reference unresolved)
C_SOURCE_BRANCH=          # Source branch (foreign branch reference resolved)
C_SOURCE_BRANCH_PREFIX=   # Source branch's prefix directory - may be empty
C_TARGET_BRANCH_SPEC=     # Target branch (foreign branch reference unresolved)
C_TARGET_BRANCH=          # Target branch (foreign branch reference resolved)
C_TARGET_BRANCH_PREFIX=   # Target branch's prefix directory - never empty
C_BASE_REV=               # Base revision - default is "empty tree"
C_BASE_PREFIX=            # Prefix for base revision
C_MESSAGE=                # The final commit message
C_SOURCE_HISTORY_OFFSET=  # When autogenerating the merge commit message,
                          # include all commit messages from the tip of the
                          # source branch back (exclusive) to this revision
                          # Note: Ignored if empty or "empty tree".
C_LAST_PUSH_MY_REV=       # The last revision of my branch, that has been pushed
C_LAST_KNOWN_THEIR_REV=   # Changes up to and including this revision of their
                          # branch have been merged into my branch (not
                          # considering changes, that have been reverted): If the
                          # last operation was pulling, this is the revision of
                          # their branch, that has been pulled last. Else, if
                          # the operation was pushing, this is the revision of
                          # the associated merge commit created on their branch
                          # (subproject requires their branch to be unchanged
                          # when pushing, which leads to my branch and their
                          # branch being equal after a push operation)



#
# Help

function help() {
    >&2 cat << EOF
Include another branch or a subdirectory thereof as subdirectory of the
current branch. Foreign branches from different repositories are supported as
well. Subproject merges like \`git merge --squash\`, so that the history does
not become cluttered. Source branch and commit are remembered within the merge
commit's message to simplify later updates. A subproject can also be merged back
into the source branch.
    
git subproject init <my-prefix> (--their-branch=<their-branch> | <their-branch>) [-m <message>] [--format=<format>] [--their-prefix=<their-prefix>] [--filter=<filter>] [--filter-is-regexp|--filter-is-glob]
git subproject pull <my-prefix> [-m <message>] [--format=<format>] [--their-prefix=<their-prefix>] [--filter=<filter>] [--filter-is-regexp|--filter-is-glob] [--their-branch=<their-branch>] [--base=<base>] [--base-prefix=<base-prefix>] [--base-filter=<base-filter>] [--ignore-id] [--allow-empty] [--diff3|--no-diff3] [--ours|--theirs|--union]
git subproject push <my-prefix> [-m <message>] [--format=<format>] [--ignore-id] [--allow-empty]

Init:
    Copy a remote branch's content to a subdirectory <my-prefix> of the current
    branch. The command will refuse to run if <my-prefix> already exists.
    
       my-prefix: mandatory - subdirectory in which their branch will be
                  included
    their-branch: mandatory - source branch to be merged into a subdirectory of
                  the current branch; branches from the current repository and
                  branches from different repositories ("foreign" branches) are
                  allowed - the syntax "<repourl>::<branch>" is used for foreign
                  branches (they are fetched temporarily)
    their-prefix: optional - limit merging to this subdirectory of their
                  branch
          filter: optional - limit merging to the set of files matching the
                  given glob pattern (see --filter-is-glob); the pattern is is
                  matched against the file path relative to the subproject
                  directory; \`\\\` is used as escape character
  filter-is-glob: default - interpret --filter as glob pattern, such that
                  subproject mimics bash's behavior of filename expansion with
                  options 'globstar' and 'dotglob' enabled, as well as 'extglob'
                  disabled - see section 3.5.8 of the bash reference manual for
                  details; the following features are currently not supported,
                  however: predefined character classes ([:alnum:], ...),
                  equivalence classes ([=c=], ...) and matching of collating
                  symbols ([.symbol.]); in constrast to bash, multiple patterns
                  can be combined using the pipe \`|\` symbol using an or-logic
filter-is-regexp: optional - interpret --filter as perl style regular expression
                  - see \`man pcre\`
         message: optional - custom commit message
          format: optional - pass to \`git log\`'s format option when appending
                  a description of the merged history to the commit message; use
                  \`--format=\` to suppress the history

Pull:
    Update a subproject by merging changes from the upstream branch.
    This command can also be used to change the name and/or prefix of the
    upstream branch.
    
       my-prefix: mandatory - subdirectory containing an existing subproject
    their-branch: optional - change the name of the upstream branch for now and
                  the future; you might need to specify a different base for
                  merging (see below)
            base: optonal - overwrite the common-ancestor used for 3way merge;
                  this might be usefull if the source branch's history has been
                  rewritten; note - no history can be embedded into the commit
                  message when this option is used
    their-prefix: optional - change their prefix if the directory has been
                  renamed since the last update
     base-prefix: optional - overwrite the prefix applied to the common
                  ancestor; this might be necessary when specifying a custom
                  base
          filter: optional - limit merging to the set of files matching the
                  given glob pattern (see --filter-is-glob); the pattern is is
                  matched against the file path relative to the subproject
                  directory; \`\\\` is used as escape character
  filter-is-glob: default - interpret --filter as glob pattern, such that
                  subproject mimics bash's behavior of filename expansion with
                  options 'globstar' and 'dotglob' enabled, as well as 'extglob'
                  disabled - see section 3.5.8 of the bash reference manual for
                  details; the following features are currently not supported,
                  however: predefined character classes ([:alnum:], ...),
                  equivalence classes ([=c=], ...) and matching of collating
                  symbols ([.symbol.]); in constrast to bash, multiple patterns
                  can be combined using the pipe \`|\` symbol using an or-logic
filter-is-regexp: optional - interpret --filter as perl style regular expression
                  - see \`man pcre\`
     base-filter: optional - like filter, but applied to the base revision,
                  only; this option can be usefull when explicitly specifying
                  a base revision and file names have changed
         message: optional - custom commit message
          format: optional - pass to \`git log\`'s format option when appending
                  a description of the merged history to the commit message; use
                  \`--format=\` to suppress the history
           diff3: optional - show conflicts in "diff3" style, that is the common
                  ancestor's version is included in confict markers
        no-diff3: optional - disable diff3-mode when enabled by default
       ignore-id: optional - ignore the subproject id when searching their
                  branch's history for subproject commits
     allow-empty: optional - allow empty commits
            ours:
          theirs:
           union: optional - resolve conflicts favouring our (or their or both)
                  side of the lines; note: ours creates empty commits (implies
                  --allow-empty)
           
Push:
    Push local changes to the upstream branch. Refused if the upstream branch
    has changed since the last update.
    
       my-prefix: mandatory - subdirectory containing an existing subproject
         message: optional - custom commit message
          format: optional - pass to \`git log\`'s format option when appending
                  a description of the merged history to the commit message; use
                  \`--format=\` to suppress the history
       ignore-id: optional - ignore the subproject id when searching their
                  branch's history for subproject commits
     allow-empty: optional - allow empty commits
                  
Continue:
    Continue a pull/push operation after merge conflicts have been resolved.
EOF

    if [[ -n $1 ]]; then
        exit $1
    fi
    
    exit $CRITICAL_EXIT_CODE
}


#
# Functions

## 1. Read arguments

# Read command line arguments
function read-arguments() {
    local COMMON_ARGS=( "-m" "--message" "--format" )
    local INIT_ARGS=( "${COMMON_ARGS[@]}" "--their-branch" "--their-prefix" "--filter" "--filter-is-regexp" "--filter-is-glob" )
    local PULL_ARGS=( "${COMMON_ARGS[@]}" "--their-branch" "--base" "--their-prefix" "--base-prefix" "--filter" "--filter-is-regexp" "--filter-is-glob" "--base-filter" "--diff3" "--no-diff3" "--ours" "--theirs" "--union" "--ignore-id" "--allow-empty" )
    local PUSH_ARGS=( "${COMMON_ARGS[@]}" "--ignore-id" "--allow-empty" )
    local CONTINUE_ARGS=( )
    local -n ALLOWED_ARGS

    function ensure-allowed() {
        for a in "${ALLOWED_ARGS[@]}"; do
            if [[ "$1" == "$a"* ]]; then
                return 0
            fi
        done
        
        help
    }
    
    if [[ "$@" == *help* ]]; then 
        help 0
    fi

    # check mode
    IN_MODE="$1"
    case "$IN_MODE" in
        init|pull|push)
            [[ $# -lt 2 ]] && help
            IN_MY_PREFIX="$2"
            normalize-prefix "IN_MY_PREFIX"
            shift 2
            ;;
        continue)
            [[ $# -gt 1 ]] && help
            shift
            ;;
        *)
            help
            ;;
    esac
    
    # select argument set
    ALLOWED_ARGS="${IN_MODE^^}_ARGS"

    # treat THEIR_BRANCH special if in mode `init`
    if [[ "$IN_MODE" == "init" && "$1" != --* ]]; then
        IN_THEIR_BRANCH="$1"
        shift
    fi

    # parse args
    while [[ $# -gt 0 ]]
    do
        ensure-allowed $1
        local VAL="${1##*=}"
        
        case "$1" in
            --allow-empty)
                IN_ALLOW_EMPTY="true"
                ;;
            --base=*)
                IN_BASE="$VAL"
                ;;
            --base-filter=*)
                IN_BASE_FILTER="$VAL"
                ;;
            --base-prefix=*)
                IN_BASE_PREFIX="$VAL"
                normalize-prefix "IN_BASE_PREFIX"
                ;;
            --diff3)
                IN_MERGE_FILE_CONFLICT_STYLE="--diff3"
                ;;
            --filter=*)
                IN_FILTER="$VAL"
                ;;
            --filter-is-regexp)
                IN_FILTER_MODE="regexp"
                ;;
            --filter-is-glob)
                IN_FILTER_MODE="glob"
                ;;
            --format=*)
                IN_HISTORY_FORMAT="$VAL"
                ;;
            --ignore-id)
                IN_IGNORE_ID="true"
                ;;
            -m)
                IN_MESSAGE="$2"
                shift
                ;;
            --message=*)
                IN_MESSAGE="$VAL"
                ;;
            --no-diff3)
                IN_MERGE_FILE_CONFLICT_STYLE="--no-diff3"
                ;;
            --ours)
                IN_MERGE_FILE_MODE="--ours"
                IN_ALLOW_EMPTY="true"
                ;;
            --theirs)
                IN_MERGE_FILE_MODE="--theirs"
                ;;
            --their-branch=*)
                IN_THEIR_BRANCH="$VAL"
                ;;
            --their-prefix=*)
                IN_THEIR_PREFIX="$VAL"
                normalize-prefix "IN_THEIR_PREFIX"
                ;;
            --union)
                IN_MERGE_FILE_MODE="--union"
                ;;
            *)
                help
                ;;
        esac
        shift # past argument or value
    done

    [[ "$IN_MODE" == "continue" || -n "$IN_MY_PREFIX" ]] || help
    
    if [[ "$IN_FILTER_MODE" == "glob" ]]; then
        if [[ -n ${IN_FILTER:+x} ]]; then
            normalize-glob "IN_FILTER"
            glob-to-regexp "IN_FILTER"
        fi
        
        if [[ -n ${IN_BASE_FILTER:+x} ]]; then
            normalize-glob "IN_BASE_FILTER"
            glob-to-regexp "IN_BASE_FILTER"
        fi
    fi
}

## 2. Preparation

# Generate a new subproject id if C_SUBPROJECT_ID is empty.
function ensure-id() {
    if [[ -z "$C_SUBPROJECT_ID" ]]; then
        local REPO_DIR=$( git rev-parse --show-toplevel )
        local THE_DATE=$( date --rfc-3339=seconds )
        
        C_SUBPROJECT_ID=$( \
            echo "$THE_DATE-$REPO_DIR-$MY_BRANCH-$IN_MY_PREFIX" \
            | git hash-object -t blob --stdin )
    fi
}

# Parse history to figure out context variables: subproject commits are marked
# with either $PUSH_MARKERs or $PULL_MARKERs.
# Initializes all context variables accept C_MARKER and C_MESSAGE to defaults
# suitable for pulling from their branch.
function get-context() {
    local LAST_PULL_MY_REV=
    local LAST_PULL_MY_PREFIX=
    local LAST_PULL_THEIR_REV=
    local LAST_PULL_THEIR_PREFIX=
    local LAST_PUSH_MY_REV=
    local LAST_PUSH_MY_PREFIX=
    local LAST_PUSH_THEIR_REV=
    local LAST_PUSH_THEIR_PREFIX=
    
    if [[ ! -d "$IN_MY_PREFIX" ]]; then
        >&2 echo "FATAL: Prefix directory '$IN_MY_PREFIX' not found."
        return $CRITICAL_EXIT_CODE
    fi
    
    
    #
    # Parse my history
    local LAST_PULL_MY_REV=$( git rev-list -1 --first-parent "--grep=^$PULL_MARKER.*-Xmy-prefix=\"$IN_MY_PREFIX\"" HEAD )
    if [[ -z "$LAST_PULL_MY_REV" ]]; then
        >&2 echo "FATAL: Subproject $IN_MY_PREFIX not found."
        return $CRITICAL_EXIT_CODE
    fi
    
    local MY_CONFIG=$( git log -1 --format=%s%n%b $LAST_PULL_MY_REV | grep "^$PULL_MARKER" | sed -e "s/^$PULL_MARKER\s*//" )
    for opt in $MY_CONFIG; do
        local VAL=$( echo "${opt##*=}" | xargs )
        case "$opt" in
            -Xmy-prefix=*)
                LAST_PULL_MY_PREFIX="$VAL"
                ;;
            -Xtheir-prefix=*)
                set-if-zero "IN_THEIR_PREFIX" "$VAL"
                LAST_PULL_THEIR_PREFIX="$VAL"
                ;;
            -Xtheir-branch=*)
                set-if-zero "IN_THEIR_BRANCH" "$VAL"
                ;;
            -Xtheir-rev=*)
                LAST_PULL_THEIR_REV="$VAL"
                ;;
            -Xfilter=*)
                if [[ -z "$IN_FILTER" ]]; then
                    IN_FILTER="$VAL"
                fi
                if [[ -z "$IN_BASE_FILTER" ]]; then
                    IN_BASE_FILTER="$VAL"
                fi
                ;;
            -Xid=*)
                C_SUBPROJECT_ID="$VAL"
                ;;
        esac
    done
    
    
    #
    ## Resolve source & target branch
    C_SOURCE_BRANCH_SPEC="$IN_THEIR_BRANCH"
    C_SOURCE_BRANCH_PREFIX="$IN_THEIR_PREFIX"
    C_TARGET_BRANCH_SPEC="$MY_BRANCH"
    C_TARGET_BRANCH_PREFIX="$IN_MY_PREFIX"
    
    # no need to resolve my branch: no user input
    resolve-branch "C_SOURCE_BRANCH_SPEC" || return $?
    C_SOURCE_BRANCH="$C_SOURCE_BRANCH_SPEC"
    C_TARGET_BRANCH="$C_TARGET_BRANCH_SPEC"
    resolve-foreign-branch "C_SOURCE_BRANCH" || return $?
    
    
    #
    # Parse their history
    if [[ -z "$C_SUBPROJECT_ID" || -n "$IN_IGNORE_ID" ]]; then
        local LAST_PUSH_THEIR_REV=$( git rev-list -1 --first-parent --perl-regexp "--grep=^$PUSH_MARKER(?=.*-Xtheir-prefix=\"$IN_MY_PREFIX\")(?=.*-Xtheir-branch=\"$MY_BRANCH\")" $C_SOURCE_BRANCH --not $IN_BASE )
    else
        local LAST_PUSH_THEIR_REV=$( git rev-list -1 --first-parent "--grep=^$PUSH_MARKER.*-Xid=\"$C_SUBPROJECT_ID\"" $C_SOURCE_BRANCH --not $IN_BASE )
    fi
    
    if [[ -n "$LAST_PUSH_THEIR_REV" ]]; then
        local THEIR_CONFIG=$( git log -1 --format=%s%n%b $LAST_PUSH_THEIR_REV | grep "^$PUSH_MARKER" | sed -e "s/^$PUSH_MARKER\s*//")
        
        for opt in $THEIR_CONFIG; do
            local VAL=$( echo "${opt##*=}" | xargs )
            case "$opt" in
                -Xtheir-rev=*)
                    LAST_PUSH_MY_REV="$VAL"
                    ;;
                -Xtheir-prefix=*)
                    LAST_PUSH_MY_PREFIX="$VAL"
                    ;;
                -Xmy-prefix=*)
                    LAST_PUSH_THEIR_PREFIX="$VAL"
                    ;;
                *);;
            esac
        done
    fi
    
    
    #
    # Generate id if missing (old project)
    ensure-id
    
    
    #
    # Determine base & base prefix
    # + info about most recent operations
    
    C_LAST_PUSH_MY_REV="$LAST_PUSH_MY_REV"
    C_BASE_REV="$IN_BASE"
    C_BASE_PREFIX="$IN_BASE_PREFIX"
    
    # The first applicable option is chosen - base prefix is determined exactly
    # the same:
    # 1. explicit IN_BASE given by user
    # - else use the newest common ancestor, that is -
    # 2. LAST_PUSH_MY_REV is newer than LAST_PULL_MY_REV: use LAST_PUSH_MY_REV
    # 3. use LAST_PULL_THEIR_REV
    if [[ -n $LAST_PUSH_MY_REV && ( $LAST_PUSH_MY_REV == $LAST_PULL_MY_REV || -n $( git rev-list --first-parent $LAST_PULL_MY_REV..$LAST_PUSH_MY_REV ) ) ]]; then
        # last PUSH is newer than last PULL
        set-if-zero "C_BASE_REV" "$LAST_PUSH_MY_REV"
        set-if-zero "C_BASE_PREFIX" "$LAST_PUSH_MY_PREFIX"
        C_LAST_KNOWN_THEIR_REV="$LAST_PUSH_THEIR_REV"
    else
        # last PULL is newest
        set-if-zero "C_BASE_REV" "$LAST_PULL_THEIR_REV"
        set-if-zero "C_BASE_PREFIX" "$LAST_PULL_THEIR_PREFIX"
        C_LAST_KNOWN_THEIR_REV="$LAST_PULL_THEIR_REV"
    fi
    
    C_SOURCE_HISTORY_OFFSET="$C_LAST_KNOWN_THEIR_REV"
}

# Build the commit message $C_MESSAGE. The message a pull or push marker and
# either a user defined $IN_MESSAGE or the source branch's history from
# $C_LAST_KNOWN_SOURCE_REV up to the tip of the branch. If
# $C_LAST_KNOWN_SOURCE_REV is empty or "empty tree", the full history is
# considered. The history format is taken from $IN_HISTORY_FORMAT.
function finalize-message() {
    local SOURCE_REV=$( git rev-parse $C_SOURCE_BRANCH )
    local MARKER_LINE="$C_MARKER -Xid=\"$C_SUBPROJECT_ID\" -Xmy-prefix=\"$C_TARGET_BRANCH_PREFIX\" -Xtheir-branch=\"$C_SOURCE_BRANCH_SPEC\" -Xtheir-prefix=\"$C_SOURCE_BRANCH_PREFIX\" -Xtheir-rev=\"$SOURCE_REV\" -Xfilter=\"$IN_FILTER\""
    
    C_MESSAGE="$IN_MESSAGE"
    if [[ -z "$C_MESSAGE" ]]; then
        local SOURCE_DESC=
        [[ -n "$C_SOURCE_BRANCH_PREFIX" ]] \
            && SOURCE_DESC="$C_SOURCE_BRANCH_SPEC:$C_SOURCE_BRANCH_PREFIX" \
            || SOURCE_DESC="$C_SOURCE_BRANCH_SPEC:*"
        
        local TARGET_DESC=
        [[ -n "$C_TARGET_BRANCH_PREFIX" ]] \
            && TARGET_DESC="$C_TARGET_BRANCH_SPEC:$C_TARGET_BRANCH_PREFIX" \
            || TARGET_DESC="C_TARGET_BRANCH_SPEC:*"
    
        C_MESSAGE="Merge '$SOURCE_DESC' into '$TARGET_DESC'"
        
        if [[ -n "$IN_FILTER" ]]; then
            C_MESSAGE+="$NL(Filter: $IN_FILTER)"
        fi
    fi
    
    if [[ -n "$IN_HISTORY_FORMAT" ]]; then
        local LIMIT=""
        if [[ -n "$C_SOURCE_HISTORY_OFFSET" ]]; then
            LIMIT="^$C_SOURCE_HISTORY_OFFSET"
        fi
        
        local SELECTED_PATHS=( "${C_SOURCE_BRANCH_PREFIX:-.}" )
        if [[ -n "$IN_FILTER" ]]; then 
            SELECTED_PATHS=( $( git ls-files --with-tree="$C_SOURCE_BRANCH" \
                | sed -e "s/^$C_SOURCE_BRANCH_PREFIX\///"  \
                | grep --perl-regexp "$IN_FILTER" ) )
                
            if [[ -n "$REMOTE_PREFIX" ]]; then
                for ((i=0; i<${#SELECTED_PATHS[@]}; i++)); do
                    SELECTED_PATHS[$i]=\
                        "$C_SOURCE_BRANCH_PREFIX/${SELECTED_PATHS[$i]}"
                done
            fi
        fi
        
        local HISTORY=$( git log --format="$IN_HISTORY_FORMAT" $C_SOURCE_BRANCH $LIMIT -- "${SELECTED_PATHS[@]}" | grep -v -E "^\s*($PULL_MARKER|$PUSH_MARKER)" )
        if [[ -n "$HISTORY" ]]; then
            C_MESSAGE+="$NL$NL$HISTORY"
        fi
    fi
    
    C_MESSAGE+="$NL$NL$MARKER_LINE"
}

# 3. Merge & commit

# Merge and commit the merged working directory -or- when in case of remaining
# conflicts, save the current script state to be picked up by 
#`git subproject continue` and abort with exit code $CAN_CONTINUE_EXIT_CODE.
function merge-and-commit() {
    merge
    local MERGE_RESULT=$?
    
    if [[ $MERGE_RESULT -ne $CRITICAL_EXIT_CODE ]]; then
        commit || return $(( $? > $MERGE_RESULT ? $? : $MERGE_RESULT ))
    else
        return $MERGE_RESULT
    fi
}

# Merge like subtree2 strategy
function merge() {   
    local BASE_TREE="$C_BASE_REV"
    local SOURCE_TREE="$C_SOURCE_BRANCH"
    local ACTUAL_BASE_FILTER="${IN_BASE_FILTER:-$IN_FILTER}"
    
    # do the merge
    prepare-remote-tree "BASE_TREE" "$C_BASE_PREFIX" \
        "$C_TARGET_BRANCH" "$C_TARGET_BRANCH_PREFIX" \
        "$ACTUAL_BASE_FILTER" || return $?
    prepare-remote-tree "SOURCE_TREE" "$C_SOURCE_BRANCH_PREFIX" \
        "$C_TARGET_BRANCH" "$C_TARGET_BRANCH_PREFIX" \
        "$IN_FILTER" || return $?
    
    MERGE_FILE_CONFLICT_STYLE="$IN_MERGE_FILE_CONFLICT_STYLE" \
    MERGE_FILE_MODE="$IN_MERGE_FILE_MODE" \
    merge-resolve "$BASE_TREE" "$C_TARGET_BRANCH" "$SOURCE_TREE" || return $?
       
    if [[ -z "$IN_ALLOW_EMPTY" && -z "$(git status --porcelain)" ]]; then
        >&2 echo "FATAL: No changes to pull/push."
        return $CRITICAL_EXIT_CODE
    fi
}

# Commit the merged working directory or save the current script state to be
# picked up by `git subproject continue` and abort with exit code
# $CAN_CONTINUE_EXIT_CODE.
function commit() {
    if ! git diff --no-ext-diff --quiet --exit-code --diff-filter=U; then
        >&2 echo "FATAL: Committing is not possible because you have unmerged files."
        >&2 echo "HINT: Fix them up in the work tree, and then use 'git add/rm <file>'"
        >&2 echo "HINT: as appropriate to mark resolution. Finally continue with"
        >&2 echo "HINT: \`git subproject continue\`."
        
        echo "STATE_REV=$(git rev-list HEAD -1)" > "$STATE_FILE"
        
        # Preserve input & context variables
        for var in $(compgen -A variable); do
            if [[ "$var" == IN_* || "$var" == C_* ]]; then
                declare -p $var >> "$STATE_FILE"
            fi
        done
        
        exit $CAN_CONTINUE_EXIT_CODE
    fi

    local COMMIT_ARGS=""
    if [[ -n "$IN_ALLOW_EMPTY" ]]; then
        COMMIT_ARGS="--allow-empty"
    fi
    echo -n "$C_MESSAGE" | git commit $COMMIT_ARGS --file=-
}


#
# Mode implementation

function do-init() {
    if [[ -e "$IN_MY_PREFIX" ]]; then
        >&2 echo "FATAL: Prefix directory '$IN_MY_PREFIX' already exists."
        return $CRITICAL_EXIT_CODE
    fi
   
    # stage 2 - prepare
    ensure-id
    C_MARKER="$PULL_MARKER"
    C_SOURCE_BRANCH_SPEC="$IN_THEIR_BRANCH"
    C_SOURCE_BRANCH_PREFIX="$IN_THEIR_PREFIX"
    C_TARGET_BRANCH_SPEC="$MY_BRANCH"
    C_TARGET_BRANCH_PREFIX="$IN_MY_PREFIX"
    C_BASE_REV="$EMPTY_TREE"
    C_BASE_PREFIX=
    C_LAST_PUSH_MY_REV=
    C_LAST_KNOWN_THEIR_REV=
    
    resolve-branch "C_SOURCE_BRANCH_SPEC" || return $?
    C_SOURCE_BRANCH="$C_SOURCE_BRANCH_SPEC"
    C_TARGET_BRANCH="$C_TARGET_BRANCH_SPEC"
    resolve-foreign-branch "C_SOURCE_BRANCH" || return $?
    finalize-message || return $?
    
    # stage 3 - merge & commit
    merge-and-commit || return $?
}

function finish-init() { 
    :
}

function do-pull() {
    #
    # stage 2 - prepare
    C_MARKER="$PULL_MARKER"
    get-context || return $?
    finalize-message || return $?

    #
    # stage 3 - merge & commit
    merge-and-commit || return $?
}

function finish-pull() { 
    :
}

function do-push() {
    #
    # stage 2 - prepare
    C_MARKER="$PUSH_MARKER"
    get-context  || return $?
    
    # refuse to push if their side has unknown changes
    local THEIRS_HAS_CHANGED=$FALSE
    if [[ -z "$IN_FILTER" ]]; then
        # without FILTER, there's no need for a complex pipeline
        if ! git diff --no-ext-diff --quiet --exit-code \
                $C_LAST_KNOWN_THEIR_REV..$C_SOURCE_BRANCH \
                -- "$C_SOURCE_BRANCH_PREFIX"; then
            THEIRS_HAS_CHANGED=$TRUE
        fi
    else
        # with FILTER, the list of changed files needs to be filtered
        if git diff --name-only --no-ext-diff \
                --relative="$C_SOURCE_BRANCH_PREFIX" \
                $C_LAST_KNOWN_THEIR_REV..$C_SOURCE_BRANCH \
                -- "$C_SOURCE_BRANCH_PREFIX" \
                | grep -q --perl-regexp "$IN_FILTER"; then
            THEIRS_HAS_CHANGED=$TRUE
        fi
    fi
    if [[ $THEIRS_HAS_CHANGED -eq $TRUE ]]; then
        >&2 echo "FATAL: Their branch '$C_SOURCE_BRANCH_SPEC' has changes that have not been pulled."
        >&2 echo "FATAL: You need to pull these changes first!"
        exit $CRITICAL_EXIT_CODE
    fi
    
    # swap source & target branches
    swap-vars "C_SOURCE_BRANCH_SPEC" "C_TARGET_BRANCH_SPEC"
    swap-vars "C_SOURCE_BRANCH" "C_TARGET_BRANCH"
    swap-vars "C_SOURCE_BRANCH_PREFIX" "C_TARGET_BRANCH_PREFIX"
    C_SOURCE_HISTORY_OFFSET="$C_LAST_PUSH_MY_REV"
    
    # build commit message
    finalize-message
    
    #
    # stage 3 - merge & commit
    # note: need to checkout their branch first!
    git checkout -q "$C_TARGET_BRANCH" || return $CRITICAL_EXIT_CODE
    merge-and-commit || return $?
}

function finish-push() {
    git checkout -q "$MY_BRANCH" || return $?
    
    # note: source & target have been swapped by do-push!
    if [[ "$C_TARGET_BRANCH_SPEC" != "$C_TARGET_BRANCH" ]]; then
        local PARTS=( ${C_TARGET_BRANCH_SPEC//::/ } )
        local URL="${PARTS[0]}"
        local REMOTE_NAME=$(
            echo -n "${PARTS[1]}" | sed -e 's/^(refs\/)?(heads\/)?\/?//' )
        
        git push "$URL" "refs/heads/$C_TARGET_BRANCH:refs/heads/$REMOTE_NAME" \
            || return $CRITICAL_EXIT_CODE
    fi
}

function do-continue() {
    if [[ ! -f "$STATE_FILE" ]]; then
        >&2 echo "FATAL: Nothing to continue!"
        return $CRITICAL_EXIT_CODE
    fi
    
    . "$GIT_REPO/GIT_SUBPROJECT_CONTINUE"
    if [[ "$STATE_REV" != $(git rev-list HEAD -1) ]]; then
        >&2 echo "FATAL: Nothing to continue!"
        return $CRITICAL_EXIT_CODE
    fi
    
    commit
    
    rm "$STATE_FILE"
}

function finish-continue() { 
    :
}


#
# Main

# Go to root directory of the working tree
cd $(git rev-parse --show-toplevel)

read-arguments "$@"
if [[ "$IN_MODE" != "continue" ]]; then
    fail-if-dirty
fi

eval "do-$IN_MODE"
DO_STATUS=$?

eval "finish-$IN_MODE $DO_STATUS" && resolve-foreign-branch-cleanup
FINISH_STATUS=$?

[[ $DO_STATUS -ne 0 ]] && exit $DO_STATUS || exit $FINISH_STATUS