Push an existing folder

Can someone tell me where the “Push an existing folder” mandate is on the gitlab homepage for a project. The Gitlab docs, “using Git” mentions this as shown below but I cannot find it in the project page that I created.


  1. In GitLab, create a project to hold your files.
  2. Visit this project’s homepage, scroll down to Push an existing folder , and copy the command that starts with git remote add .

Did you create an empty project or did you initialise it with a README.md? When you create an empty project, it gives you the instructions on what to do to push to it from your local machine.

Also make sure when you create the project you aren’t using the create from template option. It must be the blank project option.

If I go to the gitlab docs for command-line to heading “Add a remote” I see a step in line (2) regarding the push. However, I cannot find “Push and existing folder” on the “projects homepage”.

I deleted and re-added the project on the gitlab server. I have selected the intialize README option.
When I submit this I see a new project header page, number etc. However, nowhere to I see anything about “pushing” the project to my client machine.



I think there’s a misunderstanding on the terms push and pull.

  • A Git client pushes to the Git server - remote
  • A Git client pulls changes from the Git server

When an empty (no README!) project provides you the instructions to push an existing folder, it is meant to navigate on the client into an existing folder, run git init following by adding all files, creating the first Git commit, and then add a new remote configuration, following by a git push. That way the local files are persisted in a new Git repository, and synced to the server with push. Every time you do a new change locally, you need to add, commit and push your changes.

If you already have created the project on the server, and want to get the repository on your client, you need to

  • clone the project into a local folder
  • navigate into the folder and pull the changes from the remote server


PS: Another important concept are Git branches, and Merge Requests in the GitLab Flow, which comes after the basics with Git and GitLab as remote Git server.

This was why I said create an empty project and do not initialize, so that you would see the instructions on how to push from your machine to the server.

Thanks Michael.
I understand, but probably did not describe well, the push and pull mandates.
What I am trying to do, is create a git related system on my client and PUSH it to the server. So–I have a folder on my unix machine with source, make etc.
Now I issue a “git init” from the unix machine. At this point I want to “push” the results to the git server.
To to this, per the command-line documentation, my understanding is that I need to do a git add on my client from the folder I just created. The command would be something like:
“git remote add origin git@gitlab.com:username/projectpath.git”
In order to get the proper URL I am told, in the documentation to:
“Visit this project’s homepage, scroll down to Push an existing folder, and copy the command that starts with git remote add.”
When I do this I don’t see the “Push an existing folder” phrase which contains the URL. The closest thing I can find is a URL in the “clone” button but I do not believe this is the same thing.

thanks again

Thanks Ian. I should have read your post more carefully.
I redid the work without the “readme.md” and I get a lot more information. Apparently the doc could be a little clearer on this.
So thanks to both of you and I think this solves the problem.

One final thought–I (hopefully) disassociated my file on the unix machine from git by:

  1. deleting the project in gitlab
  2. removing the .git entry on the unix machine.
    The seemed to work–I was able to allocate a new project on the server and redo the “git init” on my client.

Is this indeed the appropriate method for this?
(I find the doc to be spotty and not well organized)



can you please share the URLs and anchors you are reading in the documentation? I have a hard time following where you are at in your learning curve.


sure! Here is the URL for the doc:
Start using Git on the command line | GitLab
Probably the documentation issue is that under “Choosing a repository” they suggest using:
GitLab Tests / Sample Project · GitLab
I am defining my own repository, and the default is to define the README.md file in which case the comments that Ian mentioned are not generated. So I have to make a note to un-check this.

I am a beginner here on the learning curve. I am a physicist and contracted with a group that just started to use gitlab so I am a little out of my element.
I think the synoptic view is a little scattered but I will get it all together shortly. I need to create a block diagram showing the relations of: repos, clones, commits, branches, projects, groups. And of course these can exist both on clients and on server.
The web pages are quite artistic --but not very linear like a TOC in a book. So I am finding “things hidden behind other things” etc which makes seeing the overall picture and finding things difficult.

thanks again


thanks! I’ve shared the topic with our docs and UX teams, and Amy was so kind to reproduce the workflow and add an issue to discuss improvements: User can't find "Push an existing folder" instructions (#337975) · Issues · GitLab.org / GitLab · GitLab Please review and add your own thoughts there too :slight_smile:

You are right about the fact that a generated README hides the project instructions. One of the ideas is to populate the README with helpful instructions when generated (see this comment).

If you have a public repository, you can share the link and I’ll review and send MRs in case I spot something to get you kick-started more easily. Mermaid is a great way to visualize a Git workflow in Markdown for example :slight_smile:


Thank you for your continued support Michael.
The description of my original problem is correct and the solutions suggested would all work.

Regarding startup/ learning:
Here are some basic problems with learning gitlab:

  1. If I go to “docs.gitlab.com” I would like to see a synoptic overview showing the layout of projects, groups, branches, repos etc. Then I would like to see and example of how the branching, repo, cloning, forking etc all works but only after the above top level is described. I really need this before I need details on how to install etc.

In fact when I go to the docs page I see various particulars such as Agile, CI/CD, Security etc but no starting page about the product.

  1. Using trial and error to try to figure out the above layout, I defined some groups and some projects. But I don’t see the pattern-
    I thought that one would be a sub-set of the other. It seems vaguely like you can have projects subordinate to groups but not sure. Then I think I need to define a repo–but not sure.

Documentation is always best when it is one PDF file. Hyperlinks tend to scatter and are not easily captured and marked up by the user.



That’s true, since GitLab evolved from SCM to provide the full lifecycle in a DevOps platform with planning, CI/CD, security, monitoring and more. It may not be as intuitive for beginners with a project as it can be.

Do you think it may make sense to link GitLab Learn | GitLab more prominently?

I understand where you are coming from - as a documentation maintainer for software in the past decade, I like generated websites which are always uptodate and help avoid confusion. It is a tough job our technical writing team is doing, as GitLab is moving fast. A generated PDF would be outdated the next day.

We believe that everyone can contribute at GitLab, which is why I’d like to invite you to create feedback issues and suggestions for the docs, or suggest an edit in a Merge Request.

Unrelated, since you mentioned your background: If you are planning to write your own documentation or research papers, you probably will be using LaTeX, or a TeX variant. You can use GitLab’s CI/CD to generate PDFs.

You can learn the GitLab basics and CI/CD in this workshop I created a while ago:

It is also linked in the CI/CD getting started docs.

Let me know if there’s more I can help you with.

Kind regards,

1 Like

I looked up the gitlab/learn page. It seems to point to a “CI” page which is perhaps the same thing as gitlab?
I don’t see any doc there however–just videos.

Regarding PDFs, I usually just download the updates once in a while and come out fine unless I need details on someting. At any rate I am probably just showing my age.
Hyperlinks are OK if they are step-by-step. Too often I find myself branching back on a page. Worse is figuring out how to return to them for a particular item. And the “find” command on PDF is great here.
I do realize the difficulty for the technical writing team and I appreciate that you do this at all. I always try to work with what is given and I will do that here.
(Possibly the most difficult documentation effort I know of is the Fusion360 team. Their product is very visual oriented and tough to put into words. Videos on the other hand are too slow and not indexable so the users tend to avoid them. There forum contains thousands of redundant questions due to the doc difficultes!)

Good note on the CI/CD PDF stuff and I will report this to the team. We are expecting to use doxygen for the code but another route is valued.

Thanks for your documentation. I will try to get to this soon. Like any new product I just have to deal with the learning curve.


1 Like


thanks for your feedback - about.gitlab.com/learn indeed has learning videos all over :slight_smile: Feedback inspires discussion and thoughts, sometimes learning that our growth team has the README suggestions already in the making: Experiment: Provide guidance and a template in the default README (&5461) · Epics · GitLab.org · GitLab

doxygen to generate documentation also is a good approach, and can be automated with CI/CD. You’ll find good tutorials from the community in blog posts and alike :slight_smile: There’s also an example for to use with GitLab pages: GitLab Pages examples / doxygen · GitLab


1 Like