Bitbucket lets you set a repository's description but you may want to provide detailed information or instructions about your repository. You do this in a README file that is at the root of your repository's code base. There are several formats you can use to create a README. The steps below guide you through creating a plain text README in your local repository, adding the file to tracking, committing your change locally, and pushing the file up to the remote Bitbucket server.

• Go to your terminal window and navigate to the top level of your local repository.

  cd ~/repos/bb101repo-practice/
          
  

• Using your favorite editor, create a README file with the following content:

  Welcome to My First Repo
  -------------------------------
  This repo is a practice repo I am using to learn Bitbucket.
          
  

• Save the README file in your bb101repo-practice directory.
• When you are done, list the contents of your local repository.

  You should see something similar to the following:

  $ ls -al
  total 8
  drwxr-xr-x 4 manthony staff 136 Dec 14 11:50 .
  drwxr-xr-x 3 manthony staff 102 Dec 14 11:30 ..
  drwxr-xr-x 9 manthony staff 306 Dec 14 11:30 .git
  -rw-r--r-- 1 manthony staff 117 Dec 14 11:50 README
          
  

• Go ahead and get the status of your local repository.
  The <a href="//atlassian.com/git/tutorial/git-basics#!status">git status</a> command tells you about how your project is progressing in comparison to your Bitbucket repository. You should see something like this:

  $ git status 
  # On branch master
  #
  # Initial commit
  #
  # Untracked files:
  #  (use "git add <file>..." to include in what will be committed)
  #
  #  README
  nothing added to commit but untracked files present (use "git add" to track)
          
  

  You can see that Git is aware that you created a file in your local repository. The status output also shows you the next step, the add.

• Tell git to track your new README file using the <a href="//atlassian.com/git/tutorial/git-basics#!add">git add</a> command.

  git add README
          
  

  You must perform this step before you can commit a file. What happens if you run the status command now? Git sees that you have a new file in your local repository and that you can potentially commit it.

• Commit all the changes you added.
  Right now, the only change pending in your local repository is the new README. When you issue the <a href="//atlassian.com/git/tutorial/git-basics#!commit">commit</a> command you see this:

  $ git commit -m "adding repo instructions"
  [master (root-commit) 12ad229] adding repo instructions
   1 files changed, 3 insertions(+), 0 deletions(-)
   create mode 100644 README
          
  

  Up until this point, everything you have done is local - that is on your local system. It is not visible in your Bitbucket repository until you put it there with the push command. You can test this to see if it is true by opening the Bitbucket bb101repo Overview page in your browser. You should see that the Overview looks exactly as it did when you started.

• Go back to your local terminal window and push your committed changes using the <a href="//atlassian.com/git/tutorial/remote-repositories#!push">git push</a> command.
  You should see something similar to the following:

  $ git push -u origin master
  Password: 
  Counting objects: 3, done.
  Delta compression using up to 4 threads.
  Compressing objects: 100% (2/2), done.
  Writing objects: 100% (3/3), 303 bytes, done.
  Total 3 (delta 0), reused 0 (delta 0)
  remote: bb/acl: newuserme is allowed. accepted payload.
  To <a href="https://newuserme@bitbucket.org/newuserme/bb101repo.git">  https://newuserme@bitbucket.org/newuserme/bb101re...>
   * [new branch]   master -> master
  Branch master set up to track remote branch master from origin.
          
  

• Go to your Bitbucket bb101repo repository in your browser and click the Commits item on the menu bar.

  You should see a single commit on your repository.

Remember how the Overview page looked when you first created your repo? Take some time and explore a little. Click on buttons and travel down some links.