Complete Guide to Inserting Files with Dates in Git History

Fundamentals of Git Date Mechanisms

In the Git version control system, each commit contains two independent date pieces of information: author date and committer date. Understanding the distinction between these two dates is crucial for accurately manipulating historical records. The author date represents the original creation time, while the committer date records the actual time of committing to the repository. In most cases, these dates are identical, but they may differ during operations like rebasing or cherry-picking.

Git provides multiple ways to specify date formats, including Unix timestamp, RFC 2822, and ISO 8601 standard formats. For example, the Unix timestamp format is 1112926393 +0200, where the first part is seconds and the second part is timezone offset. The RFC 2822 format example is Thu, 07 Apr 2005 22:13:13 +0200, while the ISO 8601 format is 2005-04-07T22:13:13. These formats can be used in both the git commit --date option and environment variables.

Environment Variables and Date Overrides

By setting the environment variables GIT_AUTHOR_DATE and GIT_COMMITTER_DATE, you can override the default date values when creating new commits. These environment variables are effective for any Git command that generates new commits, including regular git commit commands and environment filters in git filter-branch.

# Using environment variables to set commit dates
GIT_AUTHOR_DATE="2023-01-15 10:30:00" GIT_COMMITTER_DATE="2023-01-15 10:30:00" git commit -m "Historical commit"

Alternatively, use the --date option to directly specify the author date:

git commit --date="2023-01-15 10:30:00" -m "Historical commit with specified date"

File Insertion in Single-Branch History

For simple single-branch repositories, using git rebase is an effective method for inserting files into historical records. This approach is suitable when you only need to add new files after specific commits.

Assuming we have the following commit history:

A---B---C---D   master

If you need to insert a new commit N after commit A, follow these steps:

# Switch to target parent commit
git checkout A
# Add file and create dated commit
git add path/to/file
git commit --date='desired-date' -m 'Add historical file'
# Tag the new commit for future reference
git tag temp-new-commit
# Return to original branch and reset baseline
git checkout master
git rebase --onto temp-new-commit A
# Clean up temporary tag
git tag -d temp-new-commit

The resulting history becomes:

A---N---B'---C'---D'   master

Modifying Existing Commits

If you need to add files to existing commits rather than creating new ones, you can use git commit --amend. This method modifies the commit content while maintaining its basic identity.

# Check out target commit
git checkout target-commit
# Add file and amend commit
git add path/to/file
git commit --amend --no-edit
# Reset baseline for subsequent commits
git checkout original-branch
git rebase --onto amended-commit target-commit

Creating New Root Commits

When you need to add files at the beginning of historical records, you can create new root commits. Git version 1.7.2 and above provides the git checkout --orphan command to simplify this process.

# Create orphan branch
git checkout --orphan new-root
# Clean workspace and add files
git rm -rf .
git add path/to/file
# Create dated root commit
GIT_AUTHOR_DATE='historical-date' git commit -m 'Initial historical commit'
# Return to main branch and reset baseline
git checkout master
git rebase --root --onto new-root
# Clean up temporary branch
git branch -d new-root

Complex Handling in Multi-Branch Environments

In complex repositories containing multiple branches, tags, or other references, git filter-branch provides more powerful history rewriting capabilities. Before using this command, strongly consider backing up the entire repository.

Basic method for adding files to all existing commits:

# Create object hash for file
new_file=$(git hash-object -w path/to/file)
# Use filter branch to add files
git filter-branch \
  --index-filter \
    'git update-index --add --cacheinfo 100644 '"$new_file"' path/to/file' \
  --tag-name-filter cat \
  -- --all
# Reset workspace
git reset --hard

Conditional file addition, including files only after specific commits:

file_path=path/to/file
before_commit=$(git rev-parse --verify TARGET_COMMIT)
file_blob=$(git hash-object -w "$file_path")

git filter-branch \
  --index-filter '
    if x=$(git rev-list -1 "$GIT_COMMIT" --not '"$before_commit"') &&
       test -n "$x"; then
         git update-index --add --cacheinfo 100644 '"$file_blob $file_path"'
    fi
  ' \
  --tag-name-filter cat \
  -- --all
git reset --hard

Inserting New Commits in Middle of History

Using git filter-branch's parent filter allows inserting new commits in the middle of historical records:

file_path=path/to/file
before_commit=$(git rev-parse --verify TARGET_PARENT)

# Create new commit
git checkout "$before_commit"
git add "$file_path"
git commit --date='historical-date'
new_commit=$(git rev-parse --verify HEAD)
file_blob=$(git rev-parse --verify HEAD:"$file_path")

git checkout -

# Use parent filter to insert commit
git filter-branch \
  --parent-filter "sed -e s/$before_commit/$new_commit/g" \
  --index-filter '
    if x=$(git rev-list -1 "$GIT_COMMIT" --not '"$new_commit"') &&
       test -n "$x"; then
         git update-index --add --cacheinfo 100644 '"$file_blob $file_path"'
    fi
  ' \
  --tag-name-filter cat \
  -- --all
git reset --hard

Practical Tips and Considerations

When working with Git historical records, several important considerations apply: First, rewriting history changes the SHA-1 hashes of commits, which may affect all references depending on these hashes. Second, if the repository has already been pushed to remote, use force push (git push --force) cautiously, as this may impact other collaborators' work.

For simple date modifications, the git commit --date option is typically the most straightforward approach. For complex historical reconstruction, git filter-branch provides the most comprehensive control but requires deeper understanding and careful operation.

In practice, testing on a repository copy first is recommended to ensure understanding of all command effects. Additionally, maintaining good commit message habits and providing clear explanations for each historical modification operation will facilitate future maintenance and understanding.