Add a file to a repository

Adding files to a repository is a small, but key, task. No matter where the code, images, or documents were created, Git tracks them after you add them to your repository.

Add an existing file

To add an existing file to your repository, either:

  • Upload the file from the GitLab UI.
  • Add a file to your repository from the command line, then push the file up to GitLab.

From the UI

If you are unfamiliar with the command line, use the Web Editor to upload a file from the GitLab UI:

  1. On the left sidebar, select Search or go to and find your project.
  2. From the project dashboard or repository, next to the branch name, select the plus icon ().
  3. From the dropdown list, select Upload file.
  4. Complete the fields. To create a merge request with the uploaded file, ensure the Start a new merge request with these changes toggle is turned on.
  5. Select Upload file.

From the command line

To add a new file from the command line:

  1. Open a terminal (or shell) window.
  2. Use the “change directory” (cd) command to go to your GitLab project’s folder. Run the cd DESTINATION command, changing DESTINATION to the location of your folder.
  3. Choose a Git branch to work in. You can either:
  4. Copy the file into the appropriate directory in your project. Use your standard tool for copying files, such as Finder in macOS, or File Explorer in Windows.
  5. In your terminal window, confirm that your file is present in the directory:
    • Windows: Use the dir command.
    • All other operating systems: Use the ls command. You should see the name of the file in the list shown.
  6. Check the status of your file with the git status command. Your file’s name should be red. Files listed in red are in your file system, but Git isn’t tracking them yet.
  7. Tell Git to track this file with the git add FILENAME command, replacing FILENAME with the name of your file.
  8. Check the status of your file again with the git status command. Your file’s name should be green. Files listed in green are tracked locally by Git, but still need to be committed and pushed.

  9. Commit (save) your file to your local copy of your project’s Git repository:

    git commit -m "DESCRIBE COMMIT IN A FEW WORDS"

  10. Push (send) your changes from your copy of the repository, up to GitLab. In this command, origin refers to the copy of the repository stored at GitLab. Replace BRANCHNAME with the name of your branch:

    git push origin BRANCHNAME

  11. Git prepares, compresses, and sends the data. Lines from the remote repository (here, GitLab) are prefixed with remote: like this:

    Enumerating objects: 9, done.
Counting objects: 100% (9/9), done.
Delta compression using up to 10 threads
Compressing objects: 100% (5/5), done.
Writing objects: 100% (5/5), 1.84 KiB | 1.84 MiB/s, done.
Total 5 (delta 3), reused 0 (delta 0), pack-reused 0
remote:
remote: To create a merge request for BRANCHNAME, visit:
remote:   https://gitlab.com/gitlab-org/gitlab/-/merge_requests/new?merge_request%5Bsource_branch%5D=BRANCHNAME
remote:
To https://gitlab.com/gitlab-org/gitlab.git
 * [new branch]                BRANCHNAME -> BRANCHNAME
branch 'BRANCHNAME' set up to track 'origin/BRANCHNAME'.

Your file is now copied from your local copy of the repository, up to the remote repository at GitLab. To create a merge request, copy the link sent back from the remote repository and paste it into a browser window.

Add a new file

To create a new file (like a README.md text file) in your repository, either: