Is there a way to represent a directory tree in a Github README.md?

Here is a useful git alias that works for me.

git config --global alias.tree '! git ls-tree --full-name --name-only -t -r HEAD | sed -e "s/[^-][^\/]*\//   |/g" -e "s/|\([^ ]\)/|-- \1/"'

Here is the output of git tree

jonavon@XPS13:~/projects/roman-numerals$ git tree
.gitignore
pom.xml
src
   |-- main
   |   |-- java
   |   |   |-- com
   |   |   |   |-- foxguardsolutions
   |   |   |   |   |-- jonavon
   |   |   |   |   |   |-- AbstractFile.java
   |   |   |   |   |   |-- roman
   |   |   |   |   |   |   |-- Main.java
   |   |   |   |   |   |   |-- Numeral.java
   |   |   |   |   |   |   |-- RomanNumberInputFile.java
   |   |   |   |   |   |   |-- RomanNumeralToDecimalEvaluator.java
   |-- test
   |   |-- java
   |   |   |-- com
   |   |   |   |-- foxguardsolutions
   |   |   |   |   |-- jonavon
   |   |   |   |   |   |-- roman
   |   |   |   |   |   |   |-- InterpretSteps.java
   |   |   |   |   |   |   |-- RunCukesTest.java
   |   |-- resources
   |   |   |-- com
   |   |   |   |-- foxguardsolutions
   |   |   |   |   |-- jonavon
   |   |   |   |   |   |-- roman
   |   |   |   |   |   |   |-- Interpret.feature
   |   |   |-- sample-input.txt

The comparable tree command

jonavon@XPS13:~/projects/roman-numerals$ tree -n
.
├── pom.xml
├── src
│   ├── main
│   │   └── java
│   │       └── com
│   │           └── foxguardsolutions
│   │               └── jonavon
│   │                   ├── AbstractFile.java
│   │                   └── roman
│   │                       ├── Main.java
│   │                       ├── Numeral.java
│   │                       ├── RomanNumberInputFile.java
│   │                       └── RomanNumeralToDecimalEvaluator.java
│   └── test
│       ├── java
│       │   └── com
│       │       └── foxguardsolutions
│       │           └── jonavon
│       │               └── roman
│       │                   ├── InterpretSteps.java
│       │                   └── RunCukesTest.java
│       └── resources
│           ├── com
│           │   └── foxguardsolutions
│           │       └── jonavon
│           │           └── roman
│           │               └── Interpret.feature
│           └── sample-input.txt
└── target
    ├── classes
    │   └── com
    │       └── foxguardsolutions
    │           └── jonavon
    │               ├── AbstractFile.class
    │               └── roman
    │                   ├── Main.class
    │                   ├── Numeral.class
    │                   ├── RomanNumberInputFile.class
    │                   └── RomanNumeralToDecimalEvaluator.class
    ├── generated-sources
    │   └── annotations
    └── maven-status
        └── maven-compiler-plugin
            └── compile
                └── default-compile
                    ├── createdFiles.lst
                    └── inputFiles.lst

30 directories, 17 files

Clearly tree has better output, but I like this way because it only shows the relevant source files and not the .git directory and compiled binaries.

Not directly, no. You'd have to hand create it and put it in yourself. Assuming you are using a *nix box locally and are using utf, then tree will generate it nicely (I believe that is what generated the example you used above).

Assuming you mean the readme.md as the documentation target, then I think the only way you could automate it would be a git pre-commit hook that ran tree and embedded it into your readme file. You'd want to do a diff to make sure you only updated the readme if the output changed.

Otoh if you are maintaining seperate docs via github pages, then what you could do, is switch to using jekyll (or another generator) locally and pushing the static pages yourself. Then you could potentially implement the changes you want either as a plugin / shell script* / manual changes (if they won't vary much), or use the same method as above.

*If you integrate it into a commit hook, you can avoid adding any extra steps to changing your pages.

I got resolver the problem in this way:

1. Insert command tree in bash.

Example

2. Create a README.md in github repository and copy bash result
3. Insert in .md file within markdown code

Example

4. See the output and be happy =)

I wrote a small script that does the trick:

#!/bin/bash

#File: tree-md

tree=$(tree -tf --noreport -I '*~' --charset ascii $1 |
       sed -e 's/| \+/  /g' -e 's/[|`]-\+/ */g' -e 's:\(* \)\(\(.*/\)\([^/]\+\)\):\1[\4](\2):g')

printf "# Project tree\n\n${tree}"

Example:

Original tree command:

$ tree
.
├── dir1
│   ├── file11.ext
│   └── file12.ext
├── dir2
│   ├── file21.ext
│   ├── file22.ext
│   └── file23.ext
├── dir3
├── file_in_root.ext
└── README.md

3 directories, 7 files

Markdown tree command:

$ ./tree-md .
# Project tree

.
 * [tree-md](./tree-md)
 * [dir2](./dir2)
   * [file21.ext](./dir2/file21.ext)
   * [file22.ext](./dir2/file22.ext)
   * [file23.ext](./dir2/file23.ext)
 * [dir1](./dir1)
   * [file11.ext](./dir1/file11.ext)
   * [file12.ext](./dir1/file12.ext)
 * [file_in_root.ext](./file_in_root.ext)
 * [README.md](./README.md)
 * [dir3](./dir3)

Rendered result:

(Links are not visible in Stackoverflow...)

Project tree

• tree-md
• dir2
  • file21.ext
  • file22.ext
  • file23.ext
• dir1
  • file11.ext
  • file12.ext
• file_in_root.ext
• README.md
• dir3