What is Git's description file?


Reading time: 15 minutes

Git generates a file named description which contains the name of the repository as set by the user. It is located at .git/description. It has a default value as an unnamed repository and the developers should place the actual project name and description in this file. It is used by Git as a default way to know the name of the repository.

It is used by GitWeb and is not considered by GitHub or GitLab.
GitWeb is a web interface for git projects. It can be used to generate a web application with search feature, RSS feed and many others. It can be seen as a native alternative to external services like GitHub.

Default value of the file description:

Unnamed repository; edit this file 'description' to name the repository.

Example of description file:

opengenus test

This description file is used in several cases such as:

  • It is the source of repository name for hooks (shell scripts of Git)
  • hooks can be used to send email to contributions in case of a new commit and in the email, the repository name (from the description file) can be placed.

As it is not supported/ used by GitHub, you will find this find in this default value for all GitHub repositories like TensorFlow.

git clone https://github.com/tensorflow/tensorflow
cd tensorflow
cd .git
ls -a

Output (content list):

.   branches  description  hooks  info  objects      refs
..  config    HEAD         index  logs  packed-refs

Edit the description file:

vi description

Add "tensorflow" to the file and save it (ESC + :wq).

Try to commit the changes:

git status

Output:

On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

We cannot even commit it with other changes.

Initial new repository

description file is created when a new git project is initialized. We will check by initializing a new git project.

Create a new folder named test and go within it:

mkdir test
cd test

Initiatize it as a git repository:

git init

Output:

Initialized empty Git repository in /home/opengenus/Desktop/test/.git/

Now, it is a git repository. Let us go into .git folder and list the contents:

cd .git
ls -a

Output:

.  ..  branches  config  description  HEAD  hooks  info  objects  refs

As we see, description file is present. If we open it, following is the content:

Unnamed repository; edit this file 'description' to name the repository.

Conclusion

You can avoid using the description file if you are working with:

  • GitHub
  • GitLab
  • Using git locally without using gitweb

The only use of description file is for:

  • gitweb
  • For developing custom hooks which will read repository name dynamically