Add files and make changes by using Git

You can use the Git command line to add files, make changes to existing files, and stash changes you don't need yet.

Add files to a Git repository

To add a new file from the command line:

1. Open a terminal.

2. Change directories until you are in your project's folder.

   cd my-project

3. Choose a Git branch to work in.

   • To create a branch: git checkout -b <branchname>
   • To switch to an existing branch: git checkout <branchname>

4. Copy the file you want to add into the directory where you want to add it.

5. Confirm that your file is in the directory:

   • Windows: dir
   • All other operating systems: ls

   The filename should be displayed.

6. Check the status of the file:

   git status

   The filename should be in red. The file is in your file system, but Git isn't tracking it yet.

7. Tell Git to track the file:

   git add <filename>

8. Check the status of the file again:

   git status

   The filename should be green. The file is tracked locally by Git, but has not been committed and pushed.

9. Commit the file to your local copy of the project's Git repository:

   git commit -m "Describe the reason for your commit here"

10. Push your changes from your copy of the repository to GitLab. In this command, origin refers to the remote copy of the repository. 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 start with remote::

    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 copied from your local copy of the repository to the remote repository.

To create a merge request, copy the link sent back from the remote repository and paste it into a browser window.

Add a file to the last commit

git add <filename>
git commit --amend

Append --no-edit to the commit command if you do not want to edit the commit message.

Make changes to existing files

When you make changes to files in a repository, Git tracks the changes against the most recent version of the checked out branch. You can use Git commands to review and commit your changes to the branch, and push your work to GitLab.

View repository status

When you add, change, or delete files or folders, Git knows about the changes. To check which files have been changed:

• From your repository, run git status.

The branch name, most recent commit, and any new or changed files are displayed. New files are displayed in green. Changed files are displayed in red.

View differences

You can display the difference (or diff) between your local changes and the most recent version of a branch. View a diff to understand your local changes before you commit them to the branch.

To view the differences between your local unstaged changes and the latest version that you cloned or pulled:

• From your repository, run git diff.

  To compare your changes against a specific branch, run git diff <branch>.

The diff is displayed:

• Lines with additions begin with a plus (+) and are displayed in green.
• Lines with removals or changes begin with a minus (-) and are displayed in red.

If the diff is large, by default only a portion of the diff is displayed. You can advance the diff with Enter, and quit back to your terminal with Q.

Add and commit local changes

When you're ready to write your changes to the branch, you can commit them. A commit includes a comment that records information about the changes, and usually becomes the new tip of the branch.

Git doesn't automatically include any files you move, change, or delete in a commit. This prevents you from accidentally including a change or file, like a temporary directory. To include changes in a commit, stage them with git add.

To stage and commit your changes:

1. From your repository, for each file or directory you want to add, run git add <file name or path>.

   To stage all files in the current working directory, run git add ..

2. Confirm that the files have been added to staging:

   git status

   The files are displayed in green.

3. To commit the staged files:

   git commit -m "<comment that describes the changes>"

The changes are committed to the branch.

Commit all changes

You can stage all your changes and commit them with one command:

git commit -a -m "<comment that describes the changes>"

Be careful your commit doesn't include files you don't want to record to the remote repository. As a rule, always check the status of your local repository before you commit changes.

Send changes to GitLab

To push all local changes to the remote repository:

git push <remote> <name-of-branch>

For example, to push your local commits to the main branch of the origin remote:

git push origin main

Sometimes Git does not allow you to push to a repository. Instead, you must force an update.

Push options

DETAILS: Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

When you push changes to a branch, you can use client-side Git push options. In Git 2.10 and later, use Git push options to:

• Skip CI jobs
• Push to merge requests

In Git 2.18 and later, you can use either the long format (--push-option) or the shorter -o:

git push -o <push_option>

In Git 2.10 to 2.17, you must use the long format:

git push --push-option=<push_option>

For server-side controls and enforcement of best practices, see push rules and server hooks.

Push options for GitLab CI/CD

You can use push options to skip a CI/CD pipeline, or pass CI/CD variables.

NOTE: Push options are not available for merge request pipelines. For more information, see issue 373212.

Push options for merge requests

Git push options can perform actions for merge requests while pushing changes:

Push options for secret push protection

You can use push options to skip secret push protection.

Push options for GitGuardian integration

You can use the same push option for Secret push protection to skip GitGuardian secret detection.

Formats for push options

If your push option requires text containing spaces, enclose the text in double quotes ("). You can omit the quotes if there are no spaces. Some examples:

git push -o merge_request.label="Label with spaces"
git push -o merge_request.label=Label-with-no-spaces

To combine push options to accomplish multiple tasks at once, use multiple -o (or --push-option) flags. This command creates a new merge request, targets a branch (my-target-branch), and sets auto-merge:

git push -o merge_request.create -o merge_request.target=my-target-branch -o merge_request.merge_when_pipeline_succeeds

Create Git aliases for common commands

Adding push options to Git commands can create very long commands. If you use the same push options frequently, create Git aliases for them. Git aliases are command-line shortcuts for longer Git commands.

To create and use a Git alias for the merge when pipeline succeeds Git push option:

1. In your terminal window, run this command:

   git config --global alias.mwps "push -o merge_request.create -o merge_request.target=main -o merge_request.merge_when_pipeline_succeeds"

2. To use the alias to push a local branch that targets the default branch (main) and auto-merges, run this command:

   git mwps origin <local-branch-name>

Feature branch workflow

To merge changes from a local branch to a feature branch, follow this workflow.

1. Clone the project if you haven't already:

   git clone git@example.com:project-name.git

2. Change directories so you are in the project directory.

3. Create a branch for your feature:

   git checkout -b feature_name

4. Write code for the feature.

5. Add the code to the staging area and add a commit message for your changes:

   git commit -am "My feature is ready"

6. Push your branch to GitLab:

   git push origin feature_name

7. Review your code: On the left sidebar, go to Code > Commits.

8. Create a merge request.

9. Your team lead reviews the code and merges it to the main branch.

Stash changes

Use git stash when you want to change to a different branch, and you want to store changes that are not ready to be committed.

• Stash:

  git stash save
  # or
  git stash
  # or with a message
  git stash save "this is a message to display on the list"

• Apply stash to keep working on it:

  git stash apply
  # or apply a specific one from out stack
  git stash apply stash@{3}

• Every time you save a stash, it gets stacked. Use list to see all of the stashes.

  git stash list
  # or for more information (log methods)
  git stash list --stat

• To clean the stack, manually remove them:

  # drop top stash
  git stash drop
  # or
  git stash drop <name>
  # to clear all history we can use
  git stash clear

• Use one command to apply and drop:

  git stash pop

• If you have conflicts, either reset or commit your changes.

• Conflicts through pop don't drop a stash afterwards.

Git stash sample workflow

1. Modify a file.
2. Stage file.
3. Stash it.
4. View the stash list.
5. Confirm no pending changes through git status.
6. Apply with git stash pop.
7. View list to confirm changes.

# Modify edit_this_file.rb file
git add .

git stash save "Saving changes from edit this file"

git stash list
git status

git stash pop
git stash list
git status

Related topics

• Add file from the UI
• Add file from the Web IDE