Normally, when you want to inspect the code that’s part of a Git repository, you clone the repository down to your local environment and open the entire project in your text editor. However, sometimes all you really want to look at is one particular file to help evaluate whether you want to explore the project further. In this case, it doesn’t make sense to clone the entire project.
Luckily, if the project you’re considering is hosted on GitLab, there are more than a few ways to download a single file instead of the entire project. This article shows you a few of these methods:
- Downloading a file directly from the browser
- Using the GitLab API
- Using Git Archive
Each of these involves tradeoffs, but depending on your level of technical experience, one of them should make the most sense for you. Let’s take a look at these three approaches.
Manually Download from the Browser
GitLab has a robust web interface that allows you to browse all the files in a repository, read the project documentation, and much more, all from right within your favorite web browser. As such, this can be one of the easiest ways to download a single file, and recent updates to the GitLab interface have made this much more intuitive. For example, if you want to download the installation instructions for Inkscape, a popular open-source image editor, you can do this right from within your browser:
- Find the URL for the GitLab repo where your file exists. In this case, it’s https://gitlab.com/inkscape/inkscape
- Click through the various folders of the project until you find the file you’re looking for. In this case, it’s in the root of the repository, so no need to click through folders.
- Click the file entry so that you can see the contents of the file. You’ll also notice that the URL now contains the name of the file. In this example, the URL would be
https://gitlab.com/inkscape/inkscape/-/blob/master/INSTALL.md, and you would be able to see the contents of the file on the screen. - You should now see a download button near the top right corner of the file in this new view. Clicking this button will either download the file to the default download location on your machine or prompt you for where you want to save the file. After selecting a location, you will have the file downloaded locally.
Compared to many of the other methods in this article, this approach can be relatively slow. If you’re looking to download files from multiple repositories or back up the same file over a period of many days or weeks, you have to take this action each and every time, and it’s difficult to automate.
However, it also requires the least technical knowledge of any of the methods discussed in this article; almost anyone who knows how to use a web browser can do it. If you’re only looking to back up a single file every once in a while or don’t have programming or command line experience, this is a great way to back up a single file from a GitLab repository.
Using the GitLab API
If you’re comfortable with the command line or are looking for a more readily automated solution, GitLab also has a REST API that allows you to download single files. You can either use one of the many API clients available or make the API call to a single file using cURL through the command line, which is what you’ll see here.
First, find the GitLab ID for the project. This is visible on the main project page.
Once you’ve found the project ID, you can construct the URL for the file you’re trying to download. For example, if you’re trying to download the installation instructions as in the last example, using the project ID you found in step one, your cURL command would be:
curl https://gitlab.com/api/v4/projects/3472737/repository/files/INSTALL.md/raw?ref=master > local_file_name
Substitute 3472737 with the project ID for the repo you’re trying to download and substitute INSTALL.md with the file you’re trying to download. If you’re attempting to download a file from any branch other than master, make sure you update the ref value as well. You can also change local_file_name to the name you want the file to be after it’s downloaded.
If your repository is not public, you’ll have to include your GitLab token in the request as well.
One of the main benefits of this method is that if you need to back up files from different repositories, you can automate the process via Bash script or a similar process. If you need to access single files from GitLab as part of a larger project, you can use one of the many API clients, making this potentially much more efficient than downloading files manually through the browser.
The downsides to this method are that it does require you to have command line or programming experience, and it isn’t as straightforward.
Using Git Archive
In our previous article about archiving single files from GitHub, we mentioned that you can download a single file from a GitHub repository via SVN. Although this is a commonly requested feature in GitLab, it’s not currently possible.
However, there is a Git command called archive, which you can use similarly to the SVN method, and GitLab does currently support that command.
The git archive command requires you to specify multiple parameters:
--remote: The path to the git repository that contains the file you are trying to copy- The name of the file that you want to copy (in our case,
INSTALL.md) -o FILENAME: The name you want the generated zip archive to have once the copy is complete.
After specifying all these parameters, the final command would look something like this:
git archive --remote=ssh://git@gitlab.com/inkscape/inkscape.git HEAD INSTALL.md -o installing.zip
This will download the INSTALL.md file that you’ve seen in the previous examples as installing.zip in your current directory.
To get to a single file, you can chain a few more commands (unzip and clean up the downloaded zip file) into a one-line command that downloads, extracts, and cleans up the original zip to leave us with just the file you want to download.
The final command looks like this:
git archive --remote=ssh://git@gitlab.com/inkscape/inkscape.git HEAD INSTALL.md -o installing.zip && unzip installing.zip && rm installing.zip
When running this yourself, you should substitute the path to your repository and file to ensure it runs properly.
Once again, this method is a bit more technical than downloading a file manually through the browser, as it assumes you have at least a basic familiarity with the command line and Git commands. But just like the cURL method, it can also be automated as part of Bash scripts or any other automation that supports Git, which can be useful.
Which Is Right for You?
Hopefully, you’ve found a solution here that works for you and your technical skills. If you’re comfortable with scripting and the command line, downloading a single file from a GitLab repository through their API can be very quick. If you’re more comfortable in a browser, using the native GitLab interface might be the best option for you.
If you need full repository backups instead of just single files or directories, check out Rewind and watch for our upcoming integrations with services like Gitlab.
Keanan Koppenhaver">
