Generate simple .gitignore on init

[vrinek]

Handles: https://github.com/azerupi/mdBook/issues/110

Generates a simple .gitignore file inside the book's destination folder with the following contents:

# Ignore everything
*

# Except this file
!.gitignore

It is intended to instruct git to ignore the auto-generated destination folder's contents.

[vrinek]

Travis can only build on nightly because of the unstable feature.

[azerupi]

First of all, thanks for doing this!

There are a couple of issues with this though:

1. You can't assume every book is going to be under version control, this should definitely be an opt-in behavior (activated through a command line flag)

2. What if the output destination is somewhere outside the git repo? For example:

   src:   /home/azerupi/Programming/Rust/mdBook/book-example/src/
   dest:  /home/azerupi/Documents/book/
   

   And that is assuming that the root of the book is the root of the git repository. A book could be a small sub-part of a bigger project.

3. I can't accept patches that don't build on stable. I test on all channels, but I target mostly stable. Unfortunately that means I can't use unstable features and until this feature gets stabilized a workaround should be used.

All in all, I think this requires a bit of work for very little gain. For now the only thing that has to be put in a .gitignore is the output path and it has to be done only once. Doing it manually is not that big of a burden 😉

In the future (after the rewrite) you will be able to set individual output paths for different renderers. Maybe it will be more useful then.

What do you think? If you still want to work on this I would be happy to discuss it further to solve the remaining issues and help you with the implementation.

[vrinek]

I can't accept patches that don't build on stable.

I agree. (I'll add it to the README 😉)

A book could be a small sub-part of a bigger project.

Git can handle multiple .gitignore files within its hierarchy (http://git-scm.com/docs/gitignore).

I don't mind putting the extra effort to get this to work because my 1st priority this period is to learn Rust. I'm also using mdbook for my own project's documentation under version control and I assume more would like to do that too as it is described as "Like Gitbook but implemented in Rust".

---

One course of action would be to 1. check for git, 2. make sure the dest dir is under the root dir. If any of the above is false, do not create a .gitignore.

Alternatively, we could check for git and display a helpful message like this:

If you intend on using version control for this book, I suggest you ignore the book directory because that's where the auto-generated assets are stored.

What do you think?

[azerupi]

Git can handle multiple .gitignore files within its hierarchy

Good to know!

One course of action would be to 1. check for git, 2. make sure the dest dir is under the root dir. If any of the above is false, do not create a .gitignore.

That is one possibility. I think the option I like the most is:

When running mdbook init prompt the user if he wants to create a gitignore (y/n), this prompt has to be skipped if the --force flag is passed. The default behavior is to not create a gitignore.
If the destination folder is outside the root folder skip the prompt.

With this strategy you don't have to check for a git folder, the user can choose for himself if he needs it or not.

Does that sound like a good plan to you?

[vrinek]

👍

---

Just for reference, this is the possibility matrix I'm aiming for (and manually testing against):

force?            y n n n
dest inside root? - y y n
confirm?          - y n -
=========================
created?          n y n n

---

Ok, I coded the last possibility but it's not something I can test as the dest is hardcoded to be created within root (https://github.com/azerupi/mdBook/blob/master/src/book/mdbook.rs#L37-L39).

[vrinek]

Updated PR description & title to reflect latest code changes.

[azerupi]

Thanks for this! :)
I have changed the printed output slightly

[vrinek]

Thanks! 😄

[vrinek]

Whoops! Looks like putting the .gitignore inside the dest folder was not such a good idea after all. mdbook build removes it on every build. 😅

I'll work on a fix.

[azerupi]

Ow yes, I forgot about that. The content of the destination folder is removed before every render to avoid having ghost files.

I would put the .gitignore in the root folder and add a line with the destination path in it. That should do the job.