Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Storing Images and Demos in your Repo

Storing Images and Demos in your Repo

In this quick walkthough you'll learn how to create a separate branch in your repo to house your screenshots and demo gifs for use in your master's readme.

How to

1. Clone a fresh copy of your repo

In order to prevent any loss of work it is best to clone the repo in a separate location to complete this task.

2. Create a new branch

Create a new branch in your repo by using git checkout --orphan assets

This will create and switch you to a new branch called "assets". The --orphan flag creates a new branch but without any prior commits. However it does still keep the working tree and index.

3. Remove files from the working tree

git rm -rf .

THIS WILL DELETE ALL FILES THAT THE WORKING TREE RECOGNIZES Any files that were not added to the tree will remain left behind in the folder.

We remove all files from the working tree since we do not want anything but our screenshots and images in this branch.

You can also check what branch you are on anytime by using git branch. The branch with the * next to it is the current branch.

4. Add your images and screenshots and commit the change

git add screenshot.png demo.gif logo.png

git commit -m "Added Assets"

4. Finally push your changes

git push origin assets

Use the images in your README

You can now use ![Demo Animation](../assets/demo.gif?raw=true) in your README to have the gif display on your master's readme.

@vitutc

This comment has been minimized.

Copy link

@vitutc vitutc commented Feb 22, 2018

Nice! Thank you for this!

@hdorgeval

This comment has been minimized.

Copy link

@hdorgeval hdorgeval commented Jun 21, 2018

Thank you! works perfectly on my repo hdorgeval/stargate with a 40 Mb animated gif.

@NewEXE

This comment has been minimized.

Copy link

@NewEXE NewEXE commented Jul 1, 2018

@hughesd22

This comment has been minimized.

Copy link

@hughesd22 hughesd22 commented Oct 10, 2018

Fantastic! Just used this to include 12 animated GIFs in my repo's README ranging from 7MB - 95MB. (Note that max file size for GitHub is 100MB, so be careful not to exceed this or you won't be able to push to repo).

@omarichatman

This comment has been minimized.

Copy link

@omarichatman omarichatman commented Jan 2, 2019

Just curious. Why do we need to clone the repo? Can we not just create a assests branch in the master and continue the steps?

@zemogle

This comment has been minimized.

Copy link

@zemogle zemogle commented Jan 3, 2019

I think the clone in step 1 is so you have a backup copy in case something goes wrong in step 3 (where you remove all your files).

@lionants02

This comment has been minimized.

Copy link

@lionants02 lionants02 commented Mar 10, 2019

Thank you very much.

@benjaminbutton13659

This comment has been minimized.

Copy link

@benjaminbutton13659 benjaminbutton13659 commented Apr 21, 2019

For me the checkout --orphan asserts did not work on its own. I also had to use git branch assets afterwards, so the branch would be listed be the command git branch. After that change everything else worked fine. Great tutorial!

@anaxilaus

This comment has been minimized.

Copy link

@anaxilaus anaxilaus commented Jun 7, 2019

Benjamin,

checkout --orphan branchName doesn't create a new branch unless you commit, because branches i.e heads are just pointers which point at commit hashes and an orphan branch doesn't have any commits to start with.

@henngelm

This comment has been minimized.

Copy link

@henngelm henngelm commented Sep 4, 2019

Perfect. thx!.

@fischgeek

This comment has been minimized.

Copy link

@fischgeek fischgeek commented Nov 14, 2019

Love that the assets are still accessible in a completely different branch! Thank you!

@rsalmei

This comment has been minimized.

Copy link

@rsalmei rsalmei commented Mar 12, 2020

Afterwards, when we want to update those images, will the old ones continue to use up space in the repo? I'm worried with the local .git becoming too bloated...

@johnbent

This comment has been minimized.

Copy link

@johnbent johnbent commented May 11, 2020

@joncardasis, what is the advantage of putting images into a separate branch? It seems like it just complicates the workflow whereas it would be equally easy to just have an images directory in the master branch. No?

@nelsyeung

This comment has been minimized.

Copy link

@nelsyeung nelsyeung commented Jun 13, 2020

@joncardasis, what is the advantage of putting images into a separate branch? It seems like it just complicates the workflow whereas it would be equally easy to just have an images directory in the master branch. No?

I quite like this new branch method because, with each image update, you can choose to wipe the previous images by wiping the branch, so that it minimises the size of your repository. It also has the advantage of not cluttering your master branch with demo images.

@mohanraj-r

This comment has been minimized.

Copy link

@mohanraj-r mohanraj-r commented Jul 31, 2020

This is helpful, thanks.
Also found this related post sharing the same steps How to Store Images for Use in README.md on GitHub

@hello2235

This comment has been minimized.

Copy link

@hello2235 hello2235 commented Mar 29, 2021

mmmmmmmmmmmmmmmmmmmmmmmmmmmmmm : )

@let4be

This comment has been minimized.

Copy link

@let4be let4be commented Jun 23, 2021

So what is the benefit of doing this say vs commiting them directly to your master and keeping them versioned along with your code?...
Exactly what problem does this approach solve?

@CarlosMurillo2897

This comment has been minimized.

Copy link

@CarlosMurillo2897 CarlosMurillo2897 commented Jul 7, 2021

Awesome, really nice post. Pretty easy.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment