When you initialize a new Git repository or clone an existing one, a hidden .git directory is created at the root of your project. This directory contains all the information required to manage the version history of your project. It's essentially the brain of your Git setup, and understanding its structure can give you deeper insights into how Git works.

Let's look at the most important contents of the .git directory:

1. config

   • This file contains the configuration for your Git repository. Settings related to remote repositories, branches, and more are stored here. For instance, when you run git config user.name "Your Name", that information is saved in this file.

2. description

   • This file is only used by the GitWeb program, so you can often ignore it. By default, it contains the text "Unnamed repository; edit this file 'description' to name the repository."

3. HEAD

   • This is a reference to the last commit in the currently checked-out branch. By default, it points to refs/heads/master.

4. index

   • This is where Git stores the staging area. When you run git add <file>, that file's changes are added to this index, ready to be included in the next commit.

5. objects

   • This directory is the core of Git's storage mechanism. All data about your repository (commit objects, tree objects, blob objects, and tag objects) is stored here. They are stored in a content-addressable fashion, using a SHA-1 hash of the object's contents as its name.

6. refs

   • This directory contains pointers to commits. The two main categories are:

     • heads: For every branch you have, there will be an entry here. For example, if you have a branch named master, you will have a file named refs/heads/master containing the SHA-1 of the latest commit in that branch.

     • tags: Contains pointers to specific commits that have been tagged.

7. logs

   • This directory keeps a record of changes made to the refs. For example, every time the HEAD moves (like with a new commit), an entry is added to the logs.

8. hooks

   • This is a place to put scripts to run on certain Git operations (like pre-commit, post-commit, etc.). By default, Git provides some sample scripts here.

9. info

   • Contains the exclude file which has patterns of files or directories that are untracked and should be ignored by Git, similar to a .gitignore but local to the repository.

10. packed-refs

• In larger repositories, refs and objects can be packed for more efficient storage. This file contains a list of refs and their corresponding SHA-1 values.

1. branches (deprecated)

• Used in very early versions of Git for something called parameterized branches. It's not used anymore in modern Git workflows.

Example: Let's say you've made a commit in the master branch. Here's a rough view of how the .git folder structures the information:

• .git/HEAD will point to the reference of the latest commit in the master branch, which would be something like ref: refs/heads/master.

• .git/refs/heads/master will contain the SHA-1 hash of the latest commit.

• The commit object, tree object, and blob objects corresponding to the latest commit will reside in the .git/objects directory.

Best practices

The .git folder is an integral part of a Git repository. It's where Git stores all the metadata, objects, and other information that allows it to track and manage the history of your project. Mishandling this folder can lead to data loss or corruption of your repository.

Here are some best practices regarding the .git folder:

1. Backup Regularly:

   • As with all important data, ensure that you have regular backups of your repository, including the .git folder.

2. Avoid Manual Changes:

   • Never edit or delete files within the .git directory manually. Always use Git commands to interact with your repository.

3. Keep It Private:

   • The .git directory contains the entire history of your project. Avoid publishing or sharing the .git directory publicly to prevent unauthorized access or leakage of sensitive data present in the commit history.

4. Gitignore Isn't for .git:

   • Never try to ignore the .git directory using .gitignore. It doesn't make sense, and it can lead to confusion.

5. Use Hooks Carefully:

   • The hooks directory inside .git allows for scripts to be executed at various stages of the Git workflow. Only use trusted scripts and ensure that they don't inadvertently modify or compromise your repository.

6. Regular Maintenance:

   • Run git gc (garbage collection) periodically. This cleans up unnecessary files and optimizes the local repository. However, use this with care and preferably not on large, shared repositories without coordination.

7. Sensitive Data:

   • If you find that sensitive data has been committed (e.g., passwords, API keys), merely deleting them and committing the changes isn't enough. The data will still be present in the history. Tools like BFG Repo-Cleaner or commands like filter-branch can be used to remove sensitive data from history, but they should be used with caution.

8. Size Considerations:

   • If your .git folder becomes too large, it might be due to large binaries or files being tracked. Consider using Git LFS (Large File Storage) for managing large files without bloating the .git folder.

9. Migration & Cloning:

   • If you wish to create a copy of your repository without the full history (just the code), avoid copying the .git folder. Instead, you can use git clone with the --depth 1 parameter for a shallow clone.

10. Corruption & Recovery:

    • In cases of corruption or issues, avoid manual fixes unless you're certain about the changes. Tools like git fsck can be used to check the integrity of objects in the repository. When in doubt, cloning a fresh copy from a remote (if available) is often safer.

11. Stay Updated:

    • Regularly update your Git software to benefit from security updates, optimizations, and other improvements.

By following these best practices, you can ensure the integrity and security of your Git repositories and their histories.

Workshop: Exploring the Fragility of .git

Understand the importance of the .git folder and recognize the consequences of mishandling it.

Every action taken in the repository affects the .git folder, making it the core of your project's history.

1. Create demo repository:

    git init demo-repo
    cd demo-repo
    echo "Hello World" > README.md
    git add README.md
    git commit -m "Initial commit"
   

   

2. Manually corrupt the repository by navigating to .git/objects and deleting or modifying a couple of object files. For example, if you delete db object in the objects folder, when running git status command it will return the following error:

   

3. Mess with HEAD by modifying .git/HEAD to point to a non-existent ref. For example, modify HEAD file manually with a text editor and change the branch name:

   

   Now if you try to run git log command you will get the following error:

   

4. To check the integrity of the database use the git fsck command:

   

5. Some lost commits can be found by running git reflog command

References

1. https://git-scm.com/docs/git-gc

2. Git Large File Storage

3. https://git-scm.com/docs/git-fsck

4. BFG Repo-Cleaner

5. https://git-scm.com/docs/git-reflog